Portfolio risk heat map — R22-PIPELINE - #439

…442)

* SCALE-SEAM (95) — element state: two read/write pairs, and why the matrix loses

Moves `lodSummary`/`setLod` and `phasing`/`setPhase` out of `client.ts` into
`api/model.ts`. They answer one question — *what state are the model's elements
in, and set it?* — and `client.ts` goes 727 -> 711, 76 methods above the STAYING
banner.

The grouping is derived, not asserted:

- identical return shape `{ total, <x>ed, prop, counts: Record<...> }`;
- both writers are `(pid, guids, <enum>, publish) -> editIfc`;
- both readers are consumed by `viewer/tools/modelStatePanels.ts` (251, 316);
- both writers sit unwired and *adjacent* on `clientCallers.test.ts`'s UNCALLED
  allowlist;
- `model.ts` already owned `/model/lod/census`, `/lod/handover-readiness` and
  `/lod/assessment`, while the base distribution `/projects/{pid}/lod` was left
  behind in `client.ts` — `lodSummary` was a sibling separated from its family.

`authoring_matrix.py` DISAGREES and is recorded as the losing vote rather than
elided. It files `set_lod` under `data` and `set_phase` under `lifecycle`,
because it categorises by the IFC output each recipe writes — an LOD stage tag
against `Massing_Phasing.Status`. Different property sets, same question, which
is (89)'s "storage is a HOW" trap. This is the first slice where the matrix has
been wrong after being right three running.

It also MEETS (94)'s objection rather than overriding it: that slice declined
`setPhase` because taking the writer alone would have stranded `phasing()`, the
reader/writer split (87) had to undo. Both halves move together here.

The four names are added to `surface.test.ts` because its floor is a slack
ratchet (788 actual vs 751 floor) — the count alone would not notice a loss —
and because the UNCALLED allowlist is about call sites, not the surface.

Verified: tsc 0, lint 0, `vitest run src/api` 27 files / 119 tests, build 0,
`test_file_sizes.py` / `test_claude_md_gates.py` / `test_roadmap_status.py` /
ruff all 0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* SCALE-SEAM (96) — the as-built question's aggregate reader, and a witness that actually bounds

Moves `lod500`, `setManufacturerInfo` and `attachOmDocument` out of `client.ts`
into `api/model.ts`, rejoining `verifyAsbuilt` and `recordAsbuiltDimension`
which (94) moved. `client.ts` goes 711 -> 698, 73 methods above the STAYING
banner.

TWO BOUNDING WITNESSES, derived independently, agreeing:

- `openAsBuiltPanel` in `viewer/tools/modelStatePanels.ts` calls exactly five
  API methods — read off that function's brace closure rather than grepped for,
  so it is the closure of a scope and not a sample. Two of the five were
  already in `model.ts`.
- The reader's own response type names its writer set field by field:
  `verified`/`by_method` from `verify_asbuilt`;
  `with_dimensions`/`dimensions_out_of_tolerance` from
  `record_asbuilt_dimension`; `with_manufacturer`/`with_serial` from
  `set_manufacturer_info`; `with_om_docs`/`om_documents` from
  `attach_om_document`. The backend route says it in prose: "Stamp elements
  with the `verify_asbuilt` recipe."

A reader whose response type enumerates its writers is a DERIVED population.
After eight slices of sampling, that is the first grouping witness here that
bounds a set instead of illustrating one.

WHAT CORROBORATES IS NOT WHAT BOUNDS. `test_lod500.py` reaches exactly three
recipes — `attach_om_document`, `set_manufacturer_info`, `verify_asbuilt` — and
OMITS `record_asbuilt_dimension`, which is unambiguously in this family. It
agrees with the answer without being able to establish it. Three slices claimed
"and no others" off a test file and were wrong all three times.

NOT CLAIMED, and said in the header, the pin, the changelog and the roadmap
rather than only in review: `attachDocument` stays in `client.ts`, takes a
`purpose` parameter, and `asbuilt_summary` counts ANY purpose-tagged document
reference — so "every writer of `with_om_docs` moves here" is false. The field
map is of the recipes each field was designed around, not of everything that
can set it.

Two sources disagree and lose for the same reason: `attach_om_document` is a
purpose-tagged wrapper of `detailing.attach_document`, and
`authoring_matrix.py` files it and `set_manufacturer_info` under `data`. The
first is a shared HELPER, the second a STORAGE bucket — the groupings (89) and
(90) each had to reject. The matrix is the losing vote twice running after
being right three times.

Also fixes the extraction helper: it terminated its brace count on the method
signature line, so a signature wrapping across two lines with no opening brace
on the first read as a 3-line method. `attachOmDocument` is 6.

Verified: tsc 0, lint 0, `vitest run src/api` 27 files / 119 tests, build 0,
ruff (the CI command, from `services/api`) 0, and `test_file_sizes.py`,
`test_claude_md_gates.py`, `test_roadmap_status.py`, `test_ruff_scope.py`,
`test_reachable.py` all 0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* SCALE-SEAM (97) — the undo stack, and a destination that looked right and was not

Moves `editHistory`, `editUndo` and `editRedo` out of `client.ts` into
`api/authoring.ts`. `client.ts` goes 698 -> 687, 70 methods above the STAYING
banner.

WHY THAT MIXIN: `editIfc`, already there, is the PUSH they pop. `authoring.py`
records the pre-edit version on every `/edit` call "so this edit can be undone",
`_restore_version` pops that stack, and `edit_history.state()` reads its depths.
One stack, and the operation that fills it was already in this file.

The types agree: both writers return `{restored, state: {can_undo, can_redo}}`,
and `state` is `editHistory`'s own return type minus the depths — the writers
hand back the reader's answer. That is a type-level relation, not the shared
`/edit/` prefix. The prefix is real and is deliberately not the argument, since
a route prefix is exactly what the verification slice was caught grouping on.

A HYPOTHESIS TESTED AND WITHDRAWN, which is the part worth keeping. "Undo
restores the prior model version" makes `model.ts` the obvious home — it owns
`modelVersions`, `versionDiff`, `versionCostDelta`. It is the wrong home: those
read `/projects/{pid}/versions` out of `bim.py`, while undo pops a DIFFERENT
stack, the `edit_history` sidecar, which `recipe_log.py` describes as a list of
file paths with "No recipe, no parameters, no actor". Two stacks, one word — and
the word is what made the wrong answer look obvious. Second withdrawal of a
plausible destination after checking it, after (93) withdrew (92)'s `HttpCore`
forecast.

THE BOUND IS WEAKER THAN (96)'s AND IS STATED THAT WAY. `app.ts`'s S4 block
wires `refreshUndo` (calling only `editHistory`) and `doUndoRedo` (calling only
`editUndo`/`editRedo`), so the union is exactly these three — but that unit is a
block delimited by reading, not a closure the braces define. It corroborates; it
does not bound. Not every set has a witness as strong as the last one's, and
promoting a block to a closure would be this sequence's own recurring defect.

Verified: tsc 0, lint 0, `vitest run src/api` 27 files / 119 tests, build 0,
ruff (the CI command, from `services/api`) 0, and `test_file_sizes.py`,
`test_claude_md_gates.py`, `test_roadmap_status.py` all 0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Correct the undo/redo republish docs — all three sites, not just the flagged one

CodeRabbit flagged `editUndo`'s docstring on #414: it says "restore the prior
model version + republish" unconditionally, but `publish` defaults to true and
can be false. Verified against the backend — `_restore_version` guards the
republish with `if publish:` — so the claim is wrong whenever a caller passes
`publish: false`.

Grepping every site of that wording found the same unconditional claim in THREE
live places, not one:

- `apps/web/src/api/authoring.ts` — `editUndo` (the flagged one)
- `services/api/src/aec_api/routers/authoring.py` — the `/edit/undo` route
- `services/api/src/aec_api/routers/authoring.py` — the `/edit/redo` route

All three now say republishing happens only when `publish`. The remaining hits
are UI button labels, where the call site never passes the flag so republish
really is unconditional, and historical CHANGELOG entries; both are correct as
written and are left alone.

Also fixes the same defect's other half in the same five lines: the declared
return type omitted `publish`, which the backend adds as `"running"` when it
republishes. Correcting the prose while leaving the type silent about the same
conditional would be the half-applied fix this sequence has twice been caught
making.

Verified: tsc 0, lint 0, `vitest run src/api` 27 files / 119 tests, build 0,
ruff (the CI command, from `services/api`) 0, `test_file_sizes.py` 0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* SCALE-SEAM (98) — detailing carriers, and a field map total over one module but not the codebase

Moves `elementDetailing`, `classify`, `applyDetailingRules`, `validateDetailing`
and `attachDocument` out of `client.ts` into a new `api/detailing.ts`.
`client.ts` goes 687 -> 665, 65 methods above the STAYING banner.

WHAT THEY ANSWER: what informational carriers are attached to this element,
write them, and which are missing?

THE WITNESS IS A 1:1 AND TOTAL FIELD-TO-WRITER MAP, the shape (96) established.
`element_detailing` walks `HasAssociations` and branches on exactly two
relationship types, and `detailing.py` holds exactly two writers, one per
response array:

  classifications[]  <-  classify        (IfcRelAssociatesClassification)
  documents[]        <-  attachDocument  (IfcRelAssociatesDocument)

The map is read out of the reader's own body, not matched on names. The other
two methods are those same writes automated and audited: `applyDetailingRules`
runs the condition-to-content rule set and writes both carrier kinds,
`validateDetailing` reports elements a rule applies to that lack the code.

TOTAL OVER THE MODULE, NOT THE CODEBASE, and the difference is the claim.
`attachOmDocument` — moved to `model.ts` in (96) — wraps the SAME
`detailing.attach_document` and also lands in `documents[]`, so "these are all
the writers of this reader's fields" is false. That overlap was recorded when it
moved, which is why it was on hand to qualify this slice rather than being found
in review.

ADJACENCY AGREED WITH THE ANSWER AND IS NOT EVIDENCE FOR IT. These five were
contiguous in `client.ts`; unlike (95), where non-contiguity was the whole
argument, a positional split would have found this set too. Stated precisely
because it looks like support.

ALSO RECORDED: `api.classify()` has no call site — `detailingSection.ts` drives
the recipe through the generic `authorAndReload` path, bypassing the typed
method, and `clientCallers.test.ts` counts it reached because it matches bare
string literals as well as calls. That looseness is deliberate per that file's
own docstring, so it is a limit of the gate rather than a defect in it.

The new mixin needs `editIfc`, so it declares `NeedsEditIfc` and composes
outside `withAuthoring`; `compositionOrder.test.ts` gains a fourth assertion.
MUTATION-CHECKED: relaxing the constraint to `Ctor<any>` produces "TS2578:
Unused '@ts-expect-error' directive" on exactly the new line, so it fails for
the reason claimed rather than merely passing.

The extraction removed 27 lines and the banner plus import added 5 back — caught
by the ratchet, not by me, the same way (94) found its own banner growth.

Verified: tsc 0, lint 0, `vitest run src/api` 27 files / 119 tests, build 0,
ruff (the CI command, from `services/api`) 0, and `test_file_sizes.py`,
`test_claude_md_gates.py`, `test_roadmap_status.py` all 0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* SCALE-SEAM (99) — the content shelf, and a destination header that was wrong until now

Moves `contentCatalog`, `placeContent` and `importContent` out of `client.ts`
into `api/authoring.ts`. `client.ts` goes 665 -> 648, 62 methods above the
STAYING banner.

WHAT THEY ANSWER: what pre-made content can I place, and place it?

THE WITNESS IS A ROLE-FOR-ROLE PARALLEL with the family shelf already in that
file, read off the signatures rather than the shared noun:

  catalog reader    familyCatalog()  {count, categories: Record<..>}
                    contentCatalog() {count, note, groups: Record<..>}
  placer            placeFamily(pid, family, position)
                    placeContent(pid, category, point, name)
  multipart import  async importFamilies(pid, file, ..)
                    async importContent(pid, file, opts)

Three roles, three methods each, matching shapes and arities. A parallel between
two method TRIPLES is structural; "both are shelves" would have been a shared
word, which is the grouping (88) and (89) each had to reject.

THE DESTINATION'S OWN FIRST LINE WAS WRONG UNTIL THIS COMMIT. `authoring.ts` has
described itself as holding "the family/content shelf" while containing ZERO
content methods — the word's only other appearances there are an HTTP header and
a sentence about IFC *type* content. The docstring stated an intended scope as
fact.

That is recorded as corroboration that was FALSE, not as evidence. A header
agreeing with the answer is worth nothing until someone checks whether it is
true, and this one had been wrong for as long as it had existed. It is the
smallest possible instance of the drift the project instructions keep warning
about.

Verified: tsc 0, lint 0, `vitest run src/api` 27 files / 119 tests, build 0,
ruff (the CI command, from `services/api`) 0, and `test_file_sizes.py`,
`test_claude_md_gates.py`, `test_roadmap_status.py` all 0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* SCALE-SEAM (100) — the element-connection pair, and a destination named at its real strength

Moves `elementConnections` and `connectElements` out of `client.ts` into
`api/model.ts`. `client.ts` goes 648 -> 642, 60 methods above the STAYING
banner.

WHAT THEY ANSWER: what is physically joined to what, and record a joint?

THE PAIR IS BOUND BY THE BACKEND NAMING ITS OWN WRITER, the (96) shape: the
`/element-connections` route docstring reads "Author edges with the
`connect_elements` recipe (POST /edit with {guid_a, guid_b})". Reader and
writer, one relationship type (IfcRelConnectsElements), both marked B5.

THE DESTINATION ARGUMENT IS WEAKER THAN THE PAIRING ARGUMENT AND IS LABELLED SO.
`model.ts` owns `modelGraphStats`, whose `by_rel` counts the IFC relationship
graph BY RELATION — IfcRelConnectsElements being one — and `graphNeighbors`,
which walks it. So this pair is one relation of a graph the file already reads,
plus its authoring verb. That is a SPECIALISATION, not an identity: the graph
methods are generic traversal over every IfcRel*, these two are one relation
with a verb attached. The pairing is evidenced; the placement is a judgement,
and collapsing the two into one confident sentence is the overstatement this
sequence keeps catching.

TWO CANDIDATES REJECTED ON CHECKABLE GROUNDS. `connections.ts` is the trap: it
is DATA-SOURCE connections — SQL, ACC, Procore — sharing nothing with this but
the English word, and it is the file a name-based search lands on first. (97)
found two version stacks behind one word; this is the same collision in a
destination rather than a source. `elements.ts` holds element ATTRIBUTES and
views, and a relationship between two elements is not an attribute of either.

`addBasePlate`/`addShearTab` did not come despite sharing `connections.py` with
these: a backend module is a HOW, the grouping (89) had to reject, and those two
author PHYSICAL assemblies rather than relationship edges.

FOUND WHILE DERIVING, RECORDED NOT FIXED: `add_connection_assembly` (B5,
IfcRelConnectsWithRealizingElements) has no client method anywhere in
`apps/web/src` — a backend recipe with no web exposure, the class (93) recorded
for three MEP recipes.

Verified: tsc 0, lint 0, `vitest run src/api` 27 files / 119 tests, build 0,
ruff (the CI command, from `services/api`) 0, and `test_file_sizes.py`,
`test_claude_md_gates.py`, `test_roadmap_status.py` all 0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* R22-ENTITLEMENT ⑤ — an agency review comment becomes an RFI somebody owns

`RecordComment` had NO outward link of any kind. An agency's comment on an
`entitlement` or `permit` was a text blob at the end of a thread: readable, and
impossible to assign, track or close. ④ made comments survive a revision — the
INBOUND half of "round-tripping"; this is the outbound half the ring entry still
listed as remaining.

`POST /projects/{pid}/modules/{key}/{rid}/comments/{cid}/promote` mints a Topic
carrying the comment text, the source record's ref and its `element_guids`, and
writes a back-link on the comment.

THE BACK-LINK IS THE IDEMPOTENCY. A second promote 409s instead of minting a
duplicate RFI — the failure mode a promote button produces on every
double-click. Both load-bearing assertions in `test_comment_promote.py` were
MUTATION-CHECKED: removing the 409 guard makes one comment mint two RFIs (the
failure output shows both `comment.promote` activity entries), and removing the
back-link write drops `topic_id` from the comment.

Follows `promote_markup` rather than inventing a second idiom — mint, carry
provenance, link back, 409, audit.

REACHABLE, NOT MERELY BUILT: the control renders beside the comment and is
replaced by "→ RFI raised" once promoted, because a button whose only remaining
outcome is a 409 is worse than no button.

Adding it turned `register.ts`'s extraction ratchet red, and the remedy is the
one that file states — extraction, never headroom. The comment thread, composer
and new control came out to `portal/register/recordComments.ts` (2,516 -> 2,505,
pin lowered with it). A genuine leaf: it touches the record's comments, the API
and a reload callback and nothing else on the class, and the directory already
holds three leaves extracted the same way.

WHAT THE PREMISE-CHECK FOUND, and it is why this slice exists. The entry's
"Remaining:" line named two things and contradicted itself on one — it listed
submittal packages flatly while the note above it said the inbound half had
shipped. Measured: the inbound view is real, but assembling a package to send is
not, because `modules/transmittal/module.json` types `items` as a textarea and
`to_company` as plain text. Package contents are prose no machine can resolve
back to the records named, and the recipient cannot be the agency an
`entitlement` names, since that is free text too. That is a SCHEMA question, not
a workflow one — which is why reading the workflow surface kept reporting it
done. The roadmap now says that instead of the flat line.

Also corrected: the roadmap's argument against picking SCALE-SEAM quoted
`client.ts` at 2,837 lines. It is 642 — copied forward through every slice since,
the exact drift the rows beside it document twice.

Verified: tsc 0, lint 0, build 0, `vitest run src/portal src/api` 50 files / 275
tests, ruff (the CI command, from `services/api`) 0, and `test_comment_promote`,
`test_modules`, `test_topic_lifecycle`, `test_reachable`, `test_declared_imports`,
`test_ruff_scope`, `test_file_sizes`, `test_claude_md_gates`,
`test_roadmap_status`, `test_doc_substance`, `test_alembic_single_head` all 0.
Full 660-suite running as a cross-check.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* R22-ENTITLEMENT ⑤ review: promotion claims the comment atomically, and a blank one no longer 500s

Two findings on #434, both reproduced before fixing and both mutation-checked after.

**A whitespace-only comment 500s on promote.** The comment route takes
`text: str = Body(...)` with no min-length, so `{"text": "   \n  "}` is a 201.
Promoting it ran `.strip().splitlines()[0]` over an empty list — IndexError.
The `or f"{key} {ref} review comment"` fallback written for exactly this case
had never been reachable at all: when the list is non-empty its first element
is never blank, so the `or` arm could not fire. The guard makes it live.

**Promotion idempotency was not atomic — and the damage is worse than a
duplicate.** `SessionLocal` is `expire_on_commit=False`, so a request that read
the comment before a concurrent promote committed keeps seeing a null back-link
for as long as it holds the session; the `if cm.topic_id` guard reads that stale
copy. A plain assignment then let the later writer overwrite the back-link,
minting a second RFI AND orphaning the first, whose Topic no comment pointed at
any more. The claim is now a conditional `UPDATE ... WHERE topic_id IS NULL`:
under Postgres read-committed the loser blocks on the winner's row lock and
re-evaluates the predicate against the committed row; under SQLite the writes
serialize to the same effect. Rolling back discards the Topic flushed a moment
earlier, so a losing promote leaves nothing behind.

The race test is deterministic rather than timing-dependent — the loser reads,
the winner commits, the loser proceeds from its stale identity map, which is the
production sequence. Mutation-checked both ways: restoring the unguarded index
raises IndexError, restoring the plain assignment fails "a stale-read promote
must be refused, not duplicated".

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* R24-REPORTS-BY-MOMENT — a finished pack can be sent, not only downloaded

`POST /projects/{pid}/jobs/{job_id}/deliver` emails any finished job's artifact
to named recipients, surfaced as **Send** beside **Download** in the job tray.

**The roadmap named the wrong blocker, one layer too high.** The entry said
making a pack a scheduled deliverable "still wants a delivery surface and SMTP".
Both already existed when that was written: `mailer.py` sends real mail (stdlib
smtplib, a Settings "Test connection" button), and `POST …/notifications/digest`
is a working assemble-then-send surface returning a per-recipient status map.
What was actually missing was one size smaller — **the mailer could not carry a
file**. That is why the entry sat: the two things it named were present, so every
look confirmed it and nobody checked the layer below.

`build_message` gained attachments. The ORDER is load-bearing: `add_alternative`
must run before `add_attachment`, or the html body lands inside the mixed part —
Python's EmailMessage refuses outright ("Cannot convert mixed to alternative"),
which the test asserts rather than assumes.

Refusals mirror the download route exactly (404 wrong project, 409 while
queued/running, 404 with no artifact) so a caller does not learn two answers to
"is this artifact ready", plus two of delivery's own: an empty recipient list is
422 rather than a silent success, and over 15 MB is 413 rather than a
per-recipient error from a server that would have bounced it anyway. An
unconfigured deployment returns 200 with every recipient `disabled`, so the UI
reads `smtp_configured` before claiming a send. The delivery is audited — a file
leaving the system is what an audit log is for.

**Not shipped, deliberately: the SCHEDULED half.** There is no scheduler of any
kind in this tree — no APScheduler, no croniter, no cron — so the existing digest
is admin-triggered and nothing runs on a date. Choosing in-process versus
external cron hitting an endpoint is a deployment decision with different
operational consequences, not a wiring task. The roadmap now says that instead of
naming two things that already ship.

Mutation-checked, four ways on the route and one on the tray: dropping the
empty-recipient refusal reproduces the silent success it exists to prevent (200
with `"results":{}`); dropping the size cap admits 15 MB + 1; ignoring
attachments loses the file; attaching before the alternative raises; and ungating
Send from `hasArtifact` offers it on a job with nothing to send.

The client-caller gate did its job here — it failed the build because
`deliverJobArtifact` had no screen, which is what drove the job-tray wiring
rather than shipping another endpoint nobody can reach.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Review round on #435: five findings, all verified real, all fixed

**1. A malformed recipient aborted the whole delivery (Major).** `send_email`
built the message BEFORE its try block. `EmailMessage` rejects a header value
containing CR/LF with ValueError, and this function is documented to never raise
— so one bad address raised out of the loop after earlier recipients had already
received the artifact and before the audit row was written, leaving the record
disagreeing with what happened. Construction moved inside the protected flow;
a bad address is now that recipient's "error" and nobody else's. Also built (and
discarded) on the unconfigured path, so a malformed address does not become
visible only in production.

**2. STARTTLS presented an unverified context (Major, CWE-295).** The finding's
stated reason was wrong — it said "Python 3.9 uses an unverified context" and
this repo is on 3.12 — but the conclusion holds on 3.12 too: measured,
`ssl._create_stdlib_context()` reports verify_mode=0 and check_hostname=False,
so the artifact and the SMTP password went up with no certificate check. Both
call sites now pass `ssl.create_default_context()`.

**3. The size cap ran AFTER materialising the object (Major).** `storage.get`
pulls the whole artifact into memory and `len(data)` checked it afterwards, so
the memory was already spent on exactly the payload being refused — and
concurrent callers multiply it. `storage.size(key)` already existed; the check
now runs before the read.

**4. Recipients were unbounded and undeduplicated (Major, CWE-770).** Each
address is a synchronous SMTP conversation with a 15-second timeout, so an
unbounded list occupies a worker for hours. Now de-duplicated case-insensitively
(preserving caller order) and capped at 25 — as a 422 refusal, not a silent trim,
because quietly dropping recipients is the same silent-success failure the
empty-list 422 exists to prevent.

**5. The test stole the runner's STORAGE_DIR (Minor).** `run_tests.py` assigns
`STORAGE_DIR=./_storage_{test}` and sweeps exactly that path; the test overwrote
it, so its 15 MiB blob landed somewhere the runner does not own. That is what the
suite footer's "dir(s) this runner does not own" counts, and the stray directory
was sitting on disk at 61 MB. Now `setdefault`.

Every fix is mutation-checked. Restoring the pre-fix code fails with: build
outside the try -> AssertionError on the per-recipient result map; size-after-read
-> "materialised <key>" from a patched storage.get, which proves the object was
pulled in; no cap -> 26 recipients accepted; no dedup -> a@ and A@ both served;
bare starttls() -> "called with no context — that context does NOT verify",
asserted through a fake SMTP that captures what is actually passed rather than by
reading the source.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Second review round on #435: the port fix is the root cause my first fix missed

Three new findings on the fix commit. Two were real defects, one is a design
question answered rather than obeyed.

**A mistyped SMTP port escaped the no-raise boundary (Major) — and this is the
SAME defect class the previous commit fixed, one line above the guard.** That fix
moved `build_message` inside the try and left `int(AEC_SMTP_PORT)` outside it.
Settings are stored as arbitrary strings (`settings_store.set_value(db, k,
str(v))`, no numeric validation), so a typo in the Settings form raised
ValueError straight through a function documented never to raise, aborting the
delivery loop before its audit row — exactly the failure the CR/LF fix was for.
Treating the instance instead of the class is what left it. The whole prologue is
now inside the boundary: this function returns a status for ANY input,
configuration included.

**A recipient could forge log lines (Minor, CWE-117).** Both exception handlers
logged `to` with `%s`, so CR/LF in an address writes literal newlines into the
stream and a recipient can append a plausible-looking record of its own. Now
`%r`, which escapes them — the value is still reported, never as its own line.
This one was introduced by my previous commit, not found in old code.

**Cleartext SMTP auth: warned, not refused — deliberately.** The finding asks to
reject `send_email`/`smtp_test` outright when `AEC_SMTP_TLS=0`. That is a
documented deployment choice for a self-hosted product relaying through localhost
or a trusted internal MTA, where cleartext is not an exposure; hard-refusing
would break those installs to protect against a risk they do not have. What is
not defensible is doing it silently, so a credential sent without TLS now logs a
warning naming the setting and the remedy. The password is never logged, and the
test asserts that.

Mutation-checked: %s in place of %r puts the forged line back in the stream;
moving the port parse back outside the try loses the "error" status; removing the
warning loses the cleartext notice. The password assertion was rewritten after it
passed for the wrong reason — the fixture used "p" as the password and the
haystack was full of the letter p, so it now uses a distinctive value.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Only committed capital owns anything — cap table and waterfall

`capital.cap_table` summed `commitment` across every investor whatever their
workflow state. A `prospect` carrying a $10M interest and $0 contributed took
50% of a $10M cap table and halved a real LP from 60% to 30%. It did not stop at
display: `distwaterfall` allocates `share = lp_total * (commitment / lp_commit)`
off these rows, so the prospect drew **$1,818,181.82 of a $2M distribution**
while the committed LP got $181,818.18.

**The obvious filter is wrong on its own, which is why this took a guard.**
`investor` declares `initial: prospect` and every record is stamped with it at
creation, so on a project where nobody ran the `commit` transition EVERY investor
is a prospect and filtering empties the cap table. The roadmap records this was
implemented once and made `test_distwaterfall` return 0.0 instead of $2,000,000.

`workflow_in_use` separates two readings of the same value: **a default state is
not a signal.** Until some investor has moved off the stamped initial state,
`prospect` means "nobody used the workflow" and everyone counts, exactly as
before. Once one has, `prospect` means "not committed" and the state is evidence.

Of the three options the roadmap put to the owner, this is (c). (b) — keying on
`contributed > 0` — was rejected as a domain error: in an uncalled fund an LP
with a signed commitment and no contribution yet is normal, and that rule would
zero out real LPs who simply have not been called. (a) — changing the initial
state — needs a data migration and rewires the default entry path.

Prospect rows are never dropped: they stay visible at 0%, their money reported as
`pipeline_commitment`, and they no longer sort above real owners, because rank in
a cap table reads as ownership. `by_class` follows the same denominator or the
two halves of one table contradict. The decision rides on each row as
`counts_toward_ownership` rather than being re-derived by each of seven consumers.
`exited` is evidence the workflow was used, but is not current ownership.

Mutation-checked, and one mutation earned its keep: removing the filter restores
30%/50%; dropping the `workflow_in_use` guard reproduces the recorded failure
(`test_distwaterfall` -> 0.0); and making `distwaterfall` ignore the flag was
initially NOT caught, because `test_distwaterfall`'s fixture has no prospect. That
gap is now covered through the real API, and the mutation fails with the
$1.8M-to-the-prospect split above.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* SCALE-SEAM (101) — design-phase predicted performance, client.ts 642 -> 603

Six methods out. Five to a new `apps/web/src/api/designPerformance.ts` (energy,
energyModel, energyExportUrl, carbonComplianceReport, projectCarbon) and
benchmarkCosts to cost.ts.

**The seam was drawn by earlier slices, not this one.** operations.ts's own
header records why projectCarbon did not go there — "EMBODIED carbon ... a
design-phase estimate. The GHG figures in esgSummary come from metered utility
data. Same molecule, opposite ends of the asset life" — models.ts records the
parallel call for /energy, and operations.ts does hold /energy/actual. Prediction
versus measurement, committed to twice independently. These five are the
prediction side of an axis this codebase already chose.

Not named environmental.ts on purpose: that names the TOPIC both halves share,
which is exactly what would re-blur the seam operations.ts drew. What separates
them is not subject matter but whether the number is forecast or observed.

**A planned benchmarks.ts was abandoned before any code was written.** Grepping
every /benchmarks caller showed two already live elsewhere: cost.ts holds
unitRates (/benchmarks/unit-rates) and schedule.ts holds benchmarksPullPlanning
(/benchmarks/pull-planning). So the repo had already decided that prefix
distributes by what each method ANSWERS, and a benchmarks.ts would have been
route-prefix grouping contradicting two live placements. benchmarkCosts went to
cost.ts instead, beside unitRates — the same question at a different granularity,
same low/p25/median/p75/high shape. benchmarkResponseRates and
spaceUtilBenchmarks STAYED: no existing mixin owns their question, and inventing
a home for two methods on a guess is what produced this file's UNFILED banner.

Two gates earned their keep. DOC-STRAND caught the extraction stranding
unitRates' doc comment above the inserted block — reunited, not deleted. And the
size ratchet reported 603 where `wc -l` said 602, which is the off-by-one its own
message warns about; the pin took the gate's number.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Portfolio risk heat map — R22-PIPELINE

`GET /portfolio/risk` (`risk_portfolio.py`) grids `risk_board` across the book:
projects down, the five risk engines across (Monte-Carlo schedule risk ·
predictive alerts · EVM · pre-flight gate · overdue coordination), intensity
`3·high + 2·medium + 1·low`. Rendered on Portfolio beside the executive roll-up.

`/portfolio/executive` and `/portfolio/construction` roll up *performance*;
neither could say which risk ENGINE is hot on which project. Cells come from
`risk_board.board` unchanged — same engines, same Monte-Carlo seed — so a cell
and the project's own risk panel cannot disagree. That costs a full board per
project, so the sweep is bounded by `limit` (default 25, clamped 1–100) and
reports `truncated`; the scanned set is a deterministic prefix by name, not the
riskiest projects, because ranking is what the sweep produces and so cannot
choose what to sweep.

AN EMPTY CELL IS NOT A SAFE CELL. A grid of counts renders 0 for two different
facts: this engine looked and found nothing, and this engine could not run.
`board` is fail-open per lane and already separates them, so every cell carries
a `state`; an unmeasured cell carries NO COUNTS AT ALL rather than zeros, and
the UI draws it as a dash. `coverage` reports the split. A clear signal nobody
has a basis for is worse than no heat map — the same lesson as the cap table's
stamped default state, in a second place.

`risk_board.LANES` is new and gated against a REAL board run. `board` reports
coverage under lane keys (`schedule_risk`) while its items carry source strings
(`schedule-risk`); nothing connected the two, and a roll-up must join on both.
`test_risk_portfolio.py` asserts every lane key `board` emits appears in the
table and every `source` its items carry is a value — so a lane added to `board`
alone fails rather than rendering as a column that never lights up.

Both claims mutation-checked: emitting zeros for an error cell, and dropping a
lane from `LANES`, each fail naming the shape. 664/664 backend suites,
2062 web tests, typecheck + lint + build clean.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Review round on #439 — deterministic tie-break, keyboard-operable rows

Two findings from review, both verified real before fixing.

1. STABLE TIE-BREAKER — a bug against this route's own stated contract.
`Project.name` is not unique, and `risk_portfolio`'s docstring promises a
DETERMINISTIC prefix when the sweep truncates. Ordering by name alone leaves
tied rows in whatever order the engine returns, so a tie straddling the `limit`
boundary scans a different project run to run. Now `order_by(Project.name,
Project.id)` — the primary key settles every tie.

Pinned by a test rather than taken on trust: 8 same-named projects at `limit=6`,
asserting the scan takes the four LOWEST-ID rows and not the four first
INSERTED. Mutation-checked — reverting the fix fails it with both id lists
printed. Ids are uuid4 and nothing here can pin one, so a regression escapes
with probability 1/C(8,4) = 1.4%; that number is stated in the test rather than
left implied.

2. KEYBOARD-OPERABLE HEAT-MAP ROWS. `tr.onclick` alone gives keyboard users no
way to open a project. Checking before fixing changed the fix twice:
`.kpi-click:focus-visible` already carries a focus outline in `style.css`, so
the stylesheet was written expecting these rows to be focusable and a
pointer-only handler quietly never delivered it; and `documents.ts` already has
the house idiom — `role="button"`, `tabIndex`, Enter AND Space with
`preventDefault`. Matched that rather than inventing a pattern, plus an
`aria-label` carrying the row's risk count.

Only the row this change added is fixed. The four sibling tables in the same
panel have the identical gap, but they are pre-existing code this change does
not touch; widening into them is the author's call.

Docstrings added to `_score` and `_empty_counts` — the two helpers carrying
ideas worth stating (the intensity weighting, and where a MEASURED zero is
constructed) — and to the two test stand-ins. Matches how `resource_loading.py`
treats its helpers: bare when trivial, documented when the contract is not
obvious.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Cross-project Gantt — R22-PIPELINE

The Programme card now draws a bar per project on a shared span: start, finish,
duration, which project drives the programme finish, and which are named by an
external link.

IT NEEDED NO NEW ENGINE, AND THAT IS THE FINDING. The roadmap recorded a
cross-project Gantt as missing because `schedule_viz.py` is per-project. True,
and not the whole picture: R46's `schedule_portfolio.py` already computes
`project_starts` and `project_finishes` in its one merged pass, and the route
already returned them. `apps/web/src/api/schedule.ts` declared only
`programme_finish`, `project_count` and `external_link_count` — so the dates
reached the browser and were dropped AT THE TYPE BOUNDARY before anything could
draw them. Same class as R37-TESTED-UNWIRED, one layer further out: not a route
without a caller, but a payload without a reader.

Cost of the premise-check: one grep. Cost of believing the entry: a scheduling
engine.

`programmeGantt.ts` holds the geometry as a pure function (7 unit cases); the
panel only paints what it returns.

BARS COME FROM THE MERGED PASS, never each project's standalone CPM — a project
can look comfortable alone and be critical to the programme, and its own run
would show the comfortable answer. Asserted rather than documented:
`test_programme_gantt.py` pins that the FS link pushes fit-out past enabling's
finish, and removing the link fails it with that sentence.

A PROJECT WITH ONLY ONE DATED END GETS NO BAR, and is listed with the reason.
Substituting the programme's own start or finish for the missing end draws a bar
that looks measured and is not — the risk heat map's rule arriving independently
in a second place.

Writing the test also found that an external link names activities by RECORD id:
`wbs` and `ref` are aliases resolved only for a project's own predecessor tokens,
so a link written in WBS terms is refused as "no such activity". Recorded next to
the link that uses it.

2069 web tests (205 files), typecheck + lint + build clean, structural gates
green. Backend suite running.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Review round on #440 — reject normalised dates, require the id separator,
and correct my own wording

Three findings, all verified against the code before fixing.

1. `Date` NORMALISES AN OUT-OF-RANGE DAY instead of rejecting it: "2026-02-30"
parses happily and becomes 2026-03-02, so a bad date drew a bar. Only the month
is range-checked ("2026-13-01" is NaN). `day()` now round-trips through
`toISOString()`. This one bites harder than a generic date nit, because a
normalised date IS an invented one and this module's whole rule is that it does
not draw a bar it cannot measure — the defect was in the guard, not around it.

2. PREFIX COLLISION ON PROJECT IDS. `"p10::A1".startsWith("p1")` is true, so an
external link on p10 flagged p1 as linked and left p10 plain. The separator is
now required. Verified in node rather than reasoned about.

3. MY OWN WORDING WAS FALSE. The roadmap and CHANGELOG said the dates were
"dropped at the type boundary". `HttpCore.json<T>` returns `res.json()` under an
unchecked cast — nothing filters anything at runtime. The dates were in the
parsed response all along; nothing DECLARED them, so no call site could reach
them and none did. Corrected in three places, with the correction recorded in
the roadmap rather than quietly swapped: a plausible-sounding mechanism is
exactly the kind of wrong this file exists to resist.

Both code fixes mutation-checked — reverting each fails its own new test and
nothing else. 10 geometry cases (was 7), 2072 web tests (205 files), tsc and
eslint exit 0, doc gates green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Portfolio resourcing — R22-PIPELINE's last item

`GET /portfolio/resourcing` (`resource_portfolio.py`) sums weekly CONCURRENT
resource demand per trade across projects. `?cap=` flags weeks where one trade
is over-committed across the book and names the competing projects. Rendered on
Portfolio, with the trades on more than one project marked — the only ones that
can be double-booked.

A TRADE ON THREE JOBS IN THE SAME WEEK LOOKS COMFORTABLE ON EVERY ONE OF THEM.
That is what a per-project histogram cannot show and the whole reason for the
endpoint. Proved rather than asserted: two projects at 6 units each are each
under a cap of 8 — verified by calling their own `/schedule/resource-loading?cap=8`
and getting nothing back — while the book reports 12 over the same cap.
Mutation-checked by replacing the cross-project sum with a max, which fails on
the 12-vs-6 assertion.

"BY DEPARTMENT" WAS THE WRONG SHAPE, AND THE SCHEMA SAYS SO.
`resource_assignment.trade` is labelled "Trade / discipline", and "department"
appears nowhere in the backend except a comment in `rooms.py` and a
fire-department scope clause. A department axis is a PRODUCT DECISION — what is
a department that a trade is not? — not a filter over data we hold. Raised in
the roadmap rather than invented: a dimension nobody has defined cannot be
reported honestly. The portfolio axis was the half that mattered, and it needed
no new field.

FIDELITY IS REPORTED, NOT BLENDED. A project with no assignments falls back to
activity `crew_size`, which is a crew count and not a resourced plan, so every
row carries its `source` and `fidelity` gives the split. The heat map's rule one
step along: do not let a lower-fidelity value wear the costume of a
higher-fidelity one.

The two `over_allocation` shapes are NOT interchangeable and both docstrings say
so: this one caps per trade across the book, `resource_loading`'s caps one
project's total weekly units. The test says it too — its fixture puts the
single-project trade on its own project for exactly that reason.

A GATE CAUGHT SOMETHING ON THE WAY IN, AND IT WAS A WORD. The field
`fidelity.resourced` put the substring `sourced` into the web source, and that
is the leaf of `/schedule/eot/sourced`, so `test_route_reachability` reported a
frozen-uncalled route as called. `strip_comments` was no help — the collision
was in an identifier, not prose. Renamed to `assigned`, which names its source
rather than restating an adjective. Second instance of a class that gate already
records; the note there now explains why the matcher is not the thing to change.

2072 web tests, tsc + eslint + build clean, 12 structural gates green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Roadmap truth pass + R39-DECOMP-VIEWER (17)

TWO STALE CLAIMS CORRECTED, both found by testing the entry against the tree.

R38-SYNC-2D3D's stated defect is fixed end to end. The entry said the pipeline
"discards element identity at bake time" and that "nothing in a plan can name
what it draws". `_bake_uncached` returns (guid, ifc_class, mesh) and its own
docstring credits R38-PLAN-IDENTITY; `cut_baked_guided` emits (guid, class,
polyline) with a PRODUCTION caller in the plan renderer; the SVG carries
data-guid and planPane.ts selects on it. The entry described two functions
accurately and drew the wrong conclusion because it never looked for a third.
What actually remains: it claims three open children and names none.

CLAUDE.md's viewer numbers were both stale — "twenty-eight commits" and "3,444
lines" are now 67 and 2,570. Unlike the Node and Python drifts that file already
records, this one moved in the direction that STRENGTHENS its argument, which is
the hardest kind to notice: a number that decays toward the conclusion it
supports never looks wrong.

R39-DECOMP-VIEWER (17) — field verification out of app.ts (2,571 -> 2,508).

app.ts is not a class, so REL-4's "grep the this. refs first" rule has no this.
to grep: the file is ONE 2,445-line function and everything in it is a closure.
The equivalent is how many SIBLING closures a candidate captures, and over all
fourteen candidates >=25 lines exactly ONE captured zero. buildToolsPanel
captures 14, handleKey 12, selectByGuids 6 — every other move would have been the
callback bag REL-4 warns about. Four of five free variables already travelled on
the typed ViewerCtx, so the deps object is that context narrowed.

THE NARRATIVE-CHAIN GATE REFUSED THE FIRST RATCHET ENTRY, CORRECTLY. The previous
entry ended at 2,571 and the file measured 2,570 — one line had left with no
slice recording it, the drift the roadmap cell already documents from another
lane. The entry now runs 2,571 -> 2,508 and names the stray rather than starting
at a number nobody can reproduce. Ratchet mutation-checked at 2,507.

2072 web tests, tsc + eslint + build clean, 8 structural gates green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* SCALE-SEAM (102) — counterparty risk, client.ts 603 -> 589

`prequalScores`, `coiExpiry` and `lienExposure` out to
`apps/web/src/api/counterpartyRisk.ts` — which trade partner is a risk on this
job, and why: are they qualified, are they insured, and do we owe them enough to
be liened.

THE WITNESS IS THAT THE SEAM DISAGREES WITH THE ROUTE PREFIX. Two sit under
/prequal/ and one under /payapp/lien-exposure, so a prefix grouping would have
SPLIT the set — while all three return per-counterparty rows carrying a verdict
about that counterparty: risk_band + flags, days-to-expiry, exposure +
vendors_at_risk.

That is the affirmative form of a rule this repo has only recorded negatively:
(85) rejected "they are all multipart uploads", (89) "they are all module
records", annotate.ts "they all call editIfc" after measuring 24 recipes across
nine categories. A shared mechanism is not a question. Here the mechanism argues
AGAINST the grouping and the shape of the returns argues for it, so the evidence
is not something a name could have produced.

benchmarkResponseRates sits immediately above them and STAYED: it returns
RFI/submittal turnaround and names no counterparty at all — it measures how
responsive the process is. Adjacency is not a relationship, which REL-4 recorded
three separate times this cycle.

Found on the way out: an orphaned PrequalScores type import, the same residue
slice (101) left with EnergyResult.

Ratchet 603 -> 589, mutation-checked at 588 (both the growth assertion and the
history-chain assertion fire). 2072 web tests, tsc + eslint clean, doc gates green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Review fixes on #442, and a gate for the number that keeps drifting

Four CodeRabbit findings, all verified against the tree first. The second was
self-referential and is the interesting one.

This PR corrected CLAUDE.md's stale app.ts line count from "3,444" to 2,570 --
and then R39-DECOMP-VIEWER (17), in the same PR, took the file to 2,508. The
paragraph diagnosing numbers that decay toward the conclusion they support
decayed toward its own conclusion before it merged, and a review bot found it
rather than the author.

So test_claude_md_gates.py now checks that number against the ratchet. The
existing gate asks whether a cited FILE exists; this asks whether a cited NUMBER
is still true. It is cheap only because the value is not really CLAUDE.md's to
hold: test_file_sizes.py already pins the same file at an exact size, so the
prose is a COPY of a gated value, and a copy is what drifts. Mutation-checked
both ways -- a wrong figure fails, and a REWORDED SENTENCE fails too rather than
passing on two Nones, which is the vacuous-green failure that file's own header
calls worse than no gate at all.

R38-SYNC-2D3D is CLOSED, with its children named. The entry claimed three of
four children were open and named none of them. Re-derived by grepping the tree
rather than reading the file that was already wrong: R38-SYNC-SELECT,
R38-SYNC-VIEW, R38-PLAN-TRANSFORM and R38-PLAN-IDENTITY, and
docs/roadmap-completed.md carries a check for EACH. The 2026-08-10 un-archive
was mechanically right -- a lane row pointed at nothing -- and then inherited
the restored text's open count as though the restore had verified it. Nothing
had: R38-PLAN-IDENTITY was marked done that same day, in the archive the entry
was being pulled out of. Un-archiving restores an entry's TEXT, not its truth.

NAMING THOSE CHILDREN MADE THEM ITEMS, AND THE GATES SAID SO. Four bold item
codes in roadmap.md put three new orphans in roadmapLanes.test.ts and a stale
open-vs-implemented pair in roadmapStale.test.ts. The fourth escaped only
because its line happened to contain a check mark in prose. All four now carry
an explicit marker -- passing by accident and passing by construction look
identical until something moves.

Also: completed the verbless counterparty-risk changelog entry, and gave the
bare `wc -l` in CLAUDE.md's re-measure command its argument, since an
instruction to verify that hangs on stdin is one nobody runs twice.

Verified: 2072 web tests, tsc + eslint clean, roadmap lane/stale gates green,
citation gate green and mutation-checked twice.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

---------

Co-authored-by: Claude <noreply@anthropic.com>

* SCALE-SEAM (95) — element state: two read/write pairs, and why the matrix loses

Moves `lodSummary`/`setLod` and `phasing`/`setPhase` out of `client.ts` into
`api/model.ts`. They answer one question — *what state are the model's elements
in, and set it?* — and `client.ts` goes 727 -> 711, 76 methods above the STAYING
banner.

The grouping is derived, not asserted:

- identical return shape `{ total, <x>ed, prop, counts: Record<...> }`;
- both writers are `(pid, guids, <enum>, publish) -> editIfc`;
- both readers are consumed by `viewer/tools/modelStatePanels.ts` (251, 316);
- both writers sit unwired and *adjacent* on `clientCallers.test.ts`'s UNCALLED
  allowlist;
- `model.ts` already owned `/model/lod/census`, `/lod/handover-readiness` and
  `/lod/assessment`, while the base distribution `/projects/{pid}/lod` was left
  behind in `client.ts` — `lodSummary` was a sibling separated from its family.

`authoring_matrix.py` DISAGREES and is recorded as the losing vote rather than
elided. It files `set_lod` under `data` and `set_phase` under `lifecycle`,
because it categorises by the IFC output each recipe writes — an LOD stage tag
against `Massing_Phasing.Status`. Different property sets, same question, which
is (89)'s "storage is a HOW" trap. This is the first slice where the matrix has
been wrong after being right three running.

It also MEETS (94)'s objection rather than overriding it: that slice declined
`setPhase` because taking the writer alone would have stranded `phasing()`, the
reader/writer split (87) had to undo. Both halves move together here.

The four names are added to `surface.test.ts` because its floor is a slack
ratchet (788 actual vs 751 floor) — the count alone would not notice a loss —
and because the UNCALLED allowlist is about call sites, not the surface.

Verified: tsc 0, lint 0, `vitest run src/api` 27 files / 119 tests, build 0,
`test_file_sizes.py` / `test_claude_md_gates.py` / `test_roadmap_status.py` /
ruff all 0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* SCALE-SEAM (96) — the as-built question's aggregate reader, and a witness that actually bounds

Moves `lod500`, `setManufacturerInfo` and `attachOmDocument` out of `client.ts`
into `api/model.ts`, rejoining `verifyAsbuilt` and `recordAsbuiltDimension`
which (94) moved. `client.ts` goes 711 -> 698, 73 methods above the STAYING
banner.

TWO BOUNDING WITNESSES, derived independently, agreeing:

- `openAsBuiltPanel` in `viewer/tools/modelStatePanels.ts` calls exactly five
  API methods — read off that function's brace closure rather than grepped for,
  so it is the closure of a scope and not a sample. Two of the five were
  already in `model.ts`.
- The reader's own response type names its writer set field by field:
  `verified`/`by_method` from `verify_asbuilt`;
  `with_dimensions`/`dimensions_out_of_tolerance` from
  `record_asbuilt_dimension`; `with_manufacturer`/`with_serial` from
  `set_manufacturer_info`; `with_om_docs`/`om_documents` from
  `attach_om_document`. The backend route says it in prose: "Stamp elements
  with the `verify_asbuilt` recipe."

A reader whose response type enumerates its writers is a DERIVED population.
After eight slices of sampling, that is the first grouping witness here that
bounds a set instead of illustrating one.

WHAT CORROBORATES IS NOT WHAT BOUNDS. `test_lod500.py` reaches exactly three
recipes — `attach_om_document`, `set_manufacturer_info`, `verify_asbuilt` — and
OMITS `record_asbuilt_dimension`, which is unambiguously in this family. It
agrees with the answer without being able to establish it. Three slices claimed
"and no others" off a test file and were wrong all three times.

NOT CLAIMED, and said in the header, the pin, the changelog and the roadmap
rather than only in review: `attachDocument` stays in `client.ts`, takes a
`purpose` parameter, and `asbuilt_summary` counts ANY purpose-tagged document
reference — so "every writer of `with_om_docs` moves here" is false. The field
map is of the recipes each field was designed around, not of everything that
can set it.

Two sources disagree and lose for the same reason: `attach_om_document` is a
purpose-tagged wrapper of `detailing.attach_document`, and
`authoring_matrix.py` files it and `set_manufacturer_info` under `data`. The
first is a shared HELPER, the second a STORAGE bucket — the groupings (89) and
(90) each had to reject. The matrix is the losing vote twice running after
being right three times.

Also fixes the extraction helper: it terminated its brace count on the method
signature line, so a signature wrapping across two lines with no opening brace
on the first read as a 3-line method. `attachOmDocument` is 6.

Verified: tsc 0, lint 0, `vitest run src/api` 27 files / 119 tests, build 0,
ruff (the CI command, from `services/api`) 0, and `test_file_sizes.py`,
`test_claude_md_gates.py`, `test_roadmap_status.py`, `test_ruff_scope.py`,
`test_reachable.py` all 0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* SCALE-SEAM (97) — the undo stack, and a destination that looked right and was not

Moves `editHistory`, `editUndo` and `editRedo` out of `client.ts` into
`api/authoring.ts`. `client.ts` goes 698 -> 687, 70 methods above the STAYING
banner.

WHY THAT MIXIN: `editIfc`, already there, is the PUSH they pop. `authoring.py`
records the pre-edit version on every `/edit` call "so this edit can be undone",
`_restore_version` pops that stack, and `edit_history.state()` reads its depths.
One stack, and the operation that fills it was already in this file.

The types agree: both writers return `{restored, state: {can_undo, can_redo}}`,
and `state` is `editHistory`'s own return type minus the depths — the writers
hand back the reader's answer. That is a type-level relation, not the shared
`/edit/` prefix. The prefix is real and is deliberately not the argument, since
a route prefix is exactly what the verification slice was caught grouping on.

A HYPOTHESIS TESTED AND WITHDRAWN, which is the part worth keeping. "Undo
restores the prior model version" makes `model.ts` the obvious home — it owns
`modelVersions`, `versionDiff`, `versionCostDelta`. It is the wrong home: those
read `/projects/{pid}/versions` out of `bim.py`, while undo pops a DIFFERENT
stack, the `edit_history` sidecar, which `recipe_log.py` describes as a list of
file paths with "No recipe, no parameters, no actor". Two stacks, one word — and
the word is what made the wrong answer look obvious. Second withdrawal of a
plausible destination after checking it, after (93) withdrew (92)'s `HttpCore`
forecast.

THE BOUND IS WEAKER THAN (96)'s AND IS STATED THAT WAY. `app.ts`'s S4 block
wires `refreshUndo` (calling only `editHistory`) and `doUndoRedo` (calling only
`editUndo`/`editRedo`), so the union is exactly these three — but that unit is a
block delimited by reading, not a closure the braces define. It corroborates; it
does not bound. Not every set has a witness as strong as the last one's, and
promoting a block to a closure would be this sequence's own recurring defect.

Verified: tsc 0, lint 0, `vitest run src/api` 27 files / 119 tests, build 0,
ruff (the CI command, from `services/api`) 0, and `test_file_sizes.py`,
`test_claude_md_gates.py`, `test_roadmap_status.py` all 0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Correct the undo/redo republish docs — all three sites, not just the flagged one

CodeRabbit flagged `editUndo`'s docstring on #414: it says "restore the prior
model version + republish" unconditionally, but `publish` defaults to true and
can be false. Verified against the backend — `_restore_version` guards the
republish with `if publish:` — so the claim is wrong whenever a caller passes
`publish: false`.

Grepping every site of that wording found the same unconditional claim in THREE
live places, not one:

- `apps/web/src/api/authoring.ts` — `editUndo` (the flagged one)
- `services/api/src/aec_api/routers/authoring.py` — the `/edit/undo` route
- `services/api/src/aec_api/routers/authoring.py` — the `/edit/redo` route

All three now say republishing happens only when `publish`. The remaining hits
are UI button labels, where the call site never passes the flag so republish
really is unconditional, and historical CHANGELOG entries; both are correct as
written and are left alone.

Also fixes the same defect's other half in the same five lines: the declared
return type omitted `publish`, which the backend adds as `"running"` when it
republishes. Correcting the prose while leaving the type silent about the same
conditional would be the half-applied fix this sequence has twice been caught
making.

Verified: tsc 0, lint 0, `vitest run src/api` 27 files / 119 tests, build 0,
ruff (the CI command, from `services/api`) 0, `test_file_sizes.py` 0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* SCALE-SEAM (98) — detailing carriers, and a field map total over one module but not the codebase

Moves `elementDetailing`, `classify`, `applyDetailingRules`, `validateDetailing`
and `attachDocument` out of `client.ts` into a new `api/detailing.ts`.
`client.ts` goes 687 -> 665, 65 methods above the STAYING banner.

WHAT THEY ANSWER: what informational carriers are attached to this element,
write them, and which are missing?

THE WITNESS IS A 1:1 AND TOTAL FIELD-TO-WRITER MAP, the shape (96) established.
`element_detailing` walks `HasAssociations` and branches on exactly two
relationship types, and `detailing.py` holds exactly two writers, one per
response array:

  classifications[]  <-  classify        (IfcRelAssociatesClassification)
  documents[]        <-  attachDocument  (IfcRelAssociatesDocument)

The map is read out of the reader's own body, not matched on names. The other
two methods are those same writes automated and audited: `applyDetailingRules`
runs the condition-to-content rule set and writes both carrier kinds,
`validateDetailing` reports elements a rule applies to that lack the code.

TOTAL OVER THE MODULE, NOT THE CODEBASE, and the difference is the claim.
`attachOmDocument` — moved to `model.ts` in (96) — wraps the SAME
`detailing.attach_document` and also lands in `documents[]`, so "these are all
the writers of this reader's fields" is false. That overlap was recorded when it
moved, which is why it was on hand to qualify this slice rather than being found
in review.

ADJACENCY AGREED WITH THE ANSWER AND IS NOT EVIDENCE FOR IT. These five were
contiguous in `client.ts`; unlike (95), where non-contiguity was the whole
argument, a positional split would have found this set too. Stated precisely
because it looks like support.

ALSO RECORDED: `api.classify()` has no call site — `detailingSection.ts` drives
the recipe through the generic `authorAndReload` path, bypassing the typed
method, and `clientCallers.test.ts` counts it reached because it matches bare
string literals as well as calls. That looseness is deliberate per that file's
own docstring, so it is a limit of the gate rather than a defect in it.

The new mixin needs `editIfc`, so it declares `NeedsEditIfc` and composes
outside `withAuthoring`; `compositionOrder.test.ts` gains a fourth assertion.
MUTATION-CHECKED: relaxing the constraint to `Ctor<any>` produces "TS2578:
Unused '@ts-expect-error' directive" on exactly the new line, so it fails for
the reason claimed rather than merely passing.

The extraction removed 27 lines and the banner plus import added 5 back — caught
by the ratchet, not by me, the same way (94) found its own banner growth.

Verified: tsc 0, lint 0, `vitest run src/api` 27 files / 119 tests, build 0,
ruff (the CI command, from `services/api`) 0, and `test_file_sizes.py`,
`test_claude_md_gates.py`, `test_roadmap_status.py` all 0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* SCALE-SEAM (99) — the content shelf, and a destination header that was wrong until now

Moves `contentCatalog`, `placeContent` and `importContent` out of `client.ts`
into `api/authoring.ts`. `client.ts` goes 665 -> 648, 62 methods above the
STAYING banner.

WHAT THEY ANSWER: what pre-made content can I place, and place it?

THE WITNESS IS A ROLE-FOR-ROLE PARALLEL with the family shelf already in that
file, read off the signatures rather than the shared noun:

  catalog reader    familyCatalog()  {count, categories: Record<..>}
                    contentCatalog() {count, note, groups: Record<..>}
  placer            placeFamily(pid, family, position)
                    placeContent(pid, category, point, name)
  multipart import  async importFamilies(pid, file, ..)
                    async importContent(pid, file, opts)

Three roles, three methods each, matching shapes and arities. A parallel between
two method TRIPLES is structural; "both are shelves" would have been a shared
word, which is the grouping (88) and (89) each had to reject.

THE DESTINATION'S OWN FIRST LINE WAS WRONG UNTIL THIS COMMIT. `authoring.ts` has
described itself as holding "the family/content shelf" while containing ZERO
content methods — the word's only other appearances there are an HTTP header and
a sentence about IFC *type* content. The docstring stated an intended scope as
fact.

That is recorded as corroboration that was FALSE, not as evidence. A header
agreeing with the answer is worth nothing until someone checks whether it is
true, and this one had been wrong for as long as it had existed. It is the
smallest possible instance of the drift the project instructions keep warning
about.

Verified: tsc 0, lint 0, `vitest run src/api` 27 files / 119 tests, build 0,
ruff (the CI command, from `services/api`) 0, and `test_file_sizes.py`,
`test_claude_md_gates.py`, `test_roadmap_status.py` all 0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* SCALE-SEAM (100) — the element-connection pair, and a destination named at its real strength

Moves `elementConnections` and `connectElements` out of `client.ts` into
`api/model.ts`. `client.ts` goes 648 -> 642, 60 methods above the STAYING
banner.

WHAT THEY ANSWER: what is physically joined to what, and record a joint?

THE PAIR IS BOUND BY THE BACKEND NAMING ITS OWN WRITER, the (96) shape: the
`/element-connections` route docstring reads "Author edges with the
`connect_elements` recipe (POST /edit with {guid_a, guid_b})". Reader and
writer, one relationship type (IfcRelConnectsElements), both marked B5.

THE DESTINATION ARGUMENT IS WEAKER THAN THE PAIRING ARGUMENT AND IS LABELLED SO.
`model.ts` owns `modelGraphStats`, whose `by_rel` counts the IFC relationship
graph BY RELATION — IfcRelConnectsElements being one — and `graphNeighbors`,
which walks it. So this pair is one relation of a graph the file already reads,
plus its authoring verb. That is a SPECIALISATION, not an identity: the graph
methods are generic traversal over every IfcRel*, these two are one relation
with a verb attached. The pairing is evidenced; the placement is a judgement,
and collapsing the two into one confident sentence is the overstatement this
sequence keeps catching.

TWO CANDIDATES REJECTED ON CHECKABLE GROUNDS. `connections.ts` is the trap: it
is DATA-SOURCE connections — SQL, ACC, Procore — sharing nothing with this but
the English word, and it is the file a name-based search lands on first. (97)
found two version stacks behind one word; this is the same collision in a
destination rather than a source. `elements.ts` holds element ATTRIBUTES and
views, and a relationship between two elements is not an attribute of either.

`addBasePlate`/`addShearTab` did not come despite sharing `connections.py` with
these: a backend module is a HOW, the grouping (89) had to reject, and those two
author PHYSICAL assemblies rather than relationship edges.

FOUND WHILE DERIVING, RECORDED NOT FIXED: `add_connection_assembly` (B5,
IfcRelConnectsWithRealizingElements) has no client method anywhere in
`apps/web/src` — a backend recipe with no web exposure, the class (93) recorded
for three MEP recipes.

Verified: tsc 0, lint 0, `vitest run src/api` 27 files / 119 tests, build 0,
ruff (the CI command, from `services/api`) 0, and `test_file_sizes.py`,
`test_claude_md_gates.py`, `test_roadmap_status.py` all 0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* R22-ENTITLEMENT ⑤ — an agency review comment becomes an RFI somebody owns

`RecordComment` had NO outward link of any kind. An agency's comment on an
`entitlement` or `permit` was a text blob at the end of a thread: readable, and
impossible to assign, track or close. ④ made comments survive a revision — the
INBOUND half of "round-tripping"; this is the outbound half the ring entry still
listed as remaining.

`POST /projects/{pid}/modules/{key}/{rid}/comments/{cid}/promote` mints a Topic
carrying the comment text, the source record's ref and its `element_guids`, and
writes a back-link on the comment.

THE BACK-LINK IS THE IDEMPOTENCY. A second promote 409s instead of minting a
duplicate RFI — the failure mode a promote button produces on every
double-click. Both load-bearing assertions in `test_comment_promote.py` were
MUTATION-CHECKED: removing the 409 guard makes one comment mint two RFIs (the
failure output shows both `comment.promote` activity entries), and removing the
back-link write drops `topic_id` from the comment.

Follows `promote_markup` rather than inventing a second idiom — mint, carry
provenance, link back, 409, audit.

REACHABLE, NOT MERELY BUILT: the control renders beside the comment and is
replaced by "→ RFI raised" once promoted, because a button whose only remaining
outcome is a 409 is worse than no button.

Adding it turned `register.ts`'s extraction ratchet red, and the remedy is the
one that file states — extraction, never headroom. The comment thread, composer
and new control came out to `portal/register/recordComments.ts` (2,516 -> 2,505,
pin lowered with it). A genuine leaf: it touches the record's comments, the API
and a reload callback and nothing else on the class, and the directory already
holds three leaves extracted the same way.

WHAT THE PREMISE-CHECK FOUND, and it is why this slice exists. The entry's
"Remaining:" line named two things and contradicted itself on one — it listed
submittal packages flatly while the note above it said the inbound half had
shipped. Measured: the inbound view is real, but assembling a package to send is
not, because `modules/transmittal/module.json` types `items` as a textarea and
`to_company` as plain text. Package contents are prose no machine can resolve
back to the records named, and the recipient cannot be the agency an
`entitlement` names, since that is free text too. That is a SCHEMA question, not
a workflow one — which is why reading the workflow surface kept reporting it
done. The roadmap now says that instead of the flat line.

Also corrected: the roadmap's argument against picking SCALE-SEAM quoted
`client.ts` at 2,837 lines. It is 642 — copied forward through every slice since,
the exact drift the rows beside it document twice.

Verified: tsc 0, lint 0, build 0, `vitest run src/portal src/api` 50 files / 275
tests, ruff (the CI command, from `services/api`) 0, and `test_comment_promote`,
`test_modules`, `test_topic_lifecycle`, `test_reachable`, `test_declared_imports`,
`test_ruff_scope`, `test_file_sizes`, `test_claude_md_gates`,
`test_roadmap_status`, `test_doc_substance`, `test_alembic_single_head` all 0.
Full 660-suite running as a cross-check.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* R22-ENTITLEMENT ⑤ review: promotion claims the comment atomically, and a blank one no longer 500s

Two findings on #434, both reproduced before fixing and both mutation-checked after.

**A whitespace-only comment 500s on promote.** The comment route takes
`text: str = Body(...)` with no min-length, so `{"text": "   \n  "}` is a 201.
Promoting it ran `.strip().splitlines()[0]` over an empty list — IndexError.
The `or f"{key} {ref} review comment"` fallback written for exactly this case
had never been reachable at all: when the list is non-empty its first element
is never blank, so the `or` arm could not fire. The guard makes it live.

**Promotion idempotency was not atomic — and the damage is worse than a
duplicate.** `SessionLocal` is `expire_on_commit=False`, so a request that read
the comment before a concurrent promote committed keeps seeing a null back-link
for as long as it holds the session; the `if cm.topic_id` guard reads that stale
copy. A plain assignment then let the later writer overwrite the back-link,
minting a second RFI AND orphaning the first, whose Topic no comment pointed at
any more. The claim is now a conditional `UPDATE ... WHERE topic_id IS NULL`:
under Postgres read-committed the loser blocks on the winner's row lock and
re-evaluates the predicate against the committed row; under SQLite the writes
serialize to the same effect. Rolling back discards the Topic flushed a moment
earlier, so a losing promote leaves nothing behind.

The race test is deterministic rather than timing-dependent — the loser reads,
the winner commits, the loser proceeds from its stale identity map, which is the
production sequence. Mutation-checked both ways: restoring the unguarded index
raises IndexError, restoring the plain assignment fails "a stale-read promote
must be refused, not duplicated".

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* R24-REPORTS-BY-MOMENT — a finished pack can be sent, not only downloaded

`POST /projects/{pid}/jobs/{job_id}/deliver` emails any finished job's artifact
to named recipients, surfaced as **Send** beside **Download** in the job tray.

**The roadmap named the wrong blocker, one layer too high.** The entry said
making a pack a scheduled deliverable "still wants a delivery surface and SMTP".
Both already existed when that was written: `mailer.py` sends real mail (stdlib
smtplib, a Settings "Test connection" button), and `POST …/notifications/digest`
is a working assemble-then-send surface returning a per-recipient status map.
What was actually missing was one size smaller — **the mailer could not carry a
file**. That is why the entry sat: the two things it named were present, so every
look confirmed it and nobody checked the layer below.

`build_message` gained attachments. The ORDER is load-bearing: `add_alternative`
must run before `add_attachment`, or the html body lands inside the mixed part —
Python's EmailMessage refuses outright ("Cannot convert mixed to alternative"),
which the test asserts rather than assumes.

Refusals mirror the download route exactly (404 wrong project, 409 while
queued/running, 404 with no artifact) so a caller does not learn two answers to
"is this artifact ready", plus two of delivery's own: an empty recipient list is
422 rather than a silent success, and over 15 MB is 413 rather than a
per-recipient error from a server that would have bounced it anyway. An
unconfigured deployment returns 200 with every recipient `disabled`, so the UI
reads `smtp_configured` before claiming a send. The delivery is audited — a file
leaving the system is what an audit log is for.

**Not shipped, deliberately: the SCHEDULED half.** There is no scheduler of any
kind in this tree — no APScheduler, no croniter, no cron — so the existing digest
is admin-triggered and nothing runs on a date. Choosing in-process versus
external cron hitting an endpoint is a deployment decision with different
operational consequences, not a wiring task. The roadmap now says that instead of
naming two things that already ship.

Mutation-checked, four ways on the route and one on the tray: dropping the
empty-recipient refusal reproduces the silent success it exists to prevent (200
with `"results":{}`); dropping the size cap admits 15 MB + 1; ignoring
attachments loses the file; attaching before the alternative raises; and ungating
Send from `hasArtifact` offers it on a job with nothing to send.

The client-caller gate did its job here — it failed the build because
`deliverJobArtifact` had no screen, which is what drove the job-tray wiring
rather than shipping another endpoint nobody can reach.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Review round on #435: five findings, all verified real, all fixed

**1. A malformed recipient aborted the whole delivery (Major).** `send_email`
built the message BEFORE its try block. `EmailMessage` rejects a header value
containing CR/LF with ValueError, and this function is documented to never raise
— so one bad address raised out of the loop after earlier recipients had already
received the artifact and before the audit row was written, leaving the record
disagreeing with what happened. Construction moved inside the protected flow;
a bad address is now that recipient's "error" and nobody else's. Also built (and
discarded) on the unconfigured path, so a malformed address does not become
visible only in production.

**2. STARTTLS presented an unverified context (Major, CWE-295).** The finding's
stated reason was wrong — it said "Python 3.9 uses an unverified context" and
this repo is on 3.12 — but the conclusion holds on 3.12 too: measured,
`ssl._create_stdlib_context()` reports verify_mode=0 and check_hostname=False,
so the artifact and the SMTP password went up with no certificate check. Both
call sites now pass `ssl.create_default_context()`.

**3. The size cap ran AFTER materialising the object (Major).** `storage.get`
pulls the whole artifact into memory and `len(data)` checked it afterwards, so
the memory was already spent on exactly the payload being refused — and
concurrent callers multiply it. `storage.size(key)` already existed; the check
now runs before the read.

**4. Recipients were unbounded and undeduplicated (Major, CWE-770).** Each
address is a synchronous SMTP conversation with a 15-second timeout, so an
unbounded list occupies a worker for hours. Now de-duplicated case-insensitively
(preserving caller order) and capped at 25 — as a 422 refusal, not a silent trim,
because quietly dropping recipients is the same silent-success failure the
empty-list 422 exists to prevent.

**5. The test stole the runner's STORAGE_DIR (Minor).** `run_tests.py` assigns
`STORAGE_DIR=./_storage_{test}` and sweeps exactly that path; the test overwrote
it, so its 15 MiB blob landed somewhere the runner does not own. That is what the
suite footer's "dir(s) this runner does not own" counts, and the stray directory
was sitting on disk at 61 MB. Now `setdefault`.

Every fix is mutation-checked. Restoring the pre-fix code fails with: build
outside the try -> AssertionError on the per-recipient result map; size-after-read
-> "materialised <key>" from a patched storage.get, which proves the object was
pulled in; no cap -> 26 recipients accepted; no dedup -> a@ and A@ both served;
bare starttls() -> "called with no context — that context does NOT verify",
asserted through a fake SMTP that captures what is actually passed rather than by
reading the source.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Second review round on #435: the port fix is the root cause my first fix missed

Three new findings on the fix commit. Two were real defects, one is a design
question answered rather than obeyed.

**A mistyped SMTP port escaped the no-raise boundary (Major) — and this is the
SAME defect class the previous commit fixed, one line above the guard.** That fix
moved `build_message` inside the try and left `int(AEC_SMTP_PORT)` outside it.
Settings are stored as arbitrary strings (`settings_store.set_value(db, k,
str(v))`, no numeric validation), so a typo in the Settings form raised
ValueError straight through a function documented never to raise, aborting the
delivery loop before its audit row — exactly the failure the CR/LF fix was for.
Treating the instance instead of the class is what left it. The whole prologue is
now inside the boundary: this function returns a status for ANY input,
configuration included.

**A recipient could forge log lines (Minor, CWE-117).** Both exception handlers
logged `to` with `%s`, so CR/LF in an address writes literal newlines into the
stream and a recipient can append a plausible-looking record of its own. Now
`%r`, which escapes them — the value is still reported, never as its own line.
This one was introduced by my previous commit, not found in old code.

**Cleartext SMTP auth: warned, not refused — deliberately.** The finding asks to
reject `send_email`/`smtp_test` outright when `AEC_SMTP_TLS=0`. That is a
documented deployment choice for a self-hosted product relaying through localhost
or a trusted internal MTA, where cleartext is not an exposure; hard-refusing
would break those installs to protect against a risk they do not have. What is
not defensible is doing it silently, so a credential sent without TLS now logs a
warning naming the setting and the remedy. The password is never logged, and the
test asserts that.

Mutation-checked: %s in place of %r puts the forged line back in the stream;
moving the port parse back outside the try loses the "error" status; removing the
warning loses the cleartext notice. The password assertion was rewritten after it
passed for the wrong reason — the fixture used "p" as the password and the
haystack was full of the letter p, so it now uses a distinctive value.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Only committed capital owns anything — cap table and waterfall

`capital.cap_table` summed `commitment` across every investor whatever their
workflow state. A `prospect` carrying a $10M interest and $0 contributed took
50% of a $10M cap table and halved a real LP from 60% to 30%. It did not stop at
display: `distwaterfall` allocates `share = lp_total * (commitment / lp_commit)`
off these rows, so the prospect drew **$1,818,181.82 of a $2M distribution**
while the committed LP got $181,818.18.

**The obvious filter is wrong on its own, which is why this took a guard.**
`investor` declares `initial: prospect` and every record is stamped with it at
creation, so on a project where nobody ran the `commit` transition EVERY investor
is a prospect and filtering empties the cap table. The roadmap records this was
implemented once and made `test_distwaterfall` return 0.0 instead of $2,000,000.

`workflow_in_use` separates two readings of the same value: **a default state is
not a signal.** Until some investor has moved off the stamped initial state,
`prospect` means "nobody used the workflow" and everyone counts, exactly as
before. Once one has, `prospect` means "not committed" and the state is evidence.

Of the three options the roadmap put to the owner, this is (c). (b) — keying on
`contributed > 0` — was rejected as a domain error: in an uncalled fund an LP
with a signed commitment and no contribution yet is normal, and that rule would
zero out real LPs who simply have not been called. (a) — changing the initial
state — needs a data migration and rewires the default entry path.

Prospect rows are never dropped: they stay visible at 0%, their money reported as
`pipeline_commitment`, and they no longer sort above real owners, because rank in
a cap table reads as ownership. `by_class` follows the same denominator or the
two halves of one table contradict. The decision rides on each row as
`counts_toward_ownership` rather than being re-derived by each of seven consumers.
`exited` is evidence the workflow was used, but is not current ownership.

Mutation-checked, and one mutation earned its keep: removing the filter restores
30%/50%; dropping the `workflow_in_use` guard reproduces the recorded failure
(`test_distwaterfall` -> 0.0); and making `distwaterfall` ignore the flag was
initially NOT caught, because `test_distwaterfall`'s fixture has no prospect. That
gap is now covered through the real API, and the mutation fails with the
$1.8M-to-the-prospect split above.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* SCALE-SEAM (101) — design-phase predicted performance, client.ts 642 -> 603

Six methods out. Five to a new `apps/web/src/api/designPerformance.ts` (energy,
energyModel, energyExportUrl, carbonComplianceReport, projectCarbon) and
benchmarkCosts to cost.ts.

**The seam was drawn by earlier slices, not this one.** operations.ts's own
header records why projectCarbon did not go there — "EMBODIED carbon ... a
design-phase estimate. The GHG figures in esgSummary come from metered utility
data. Same molecule, opposite ends of the asset life" — models.ts records the
parallel call for /energy, and operations.ts does hold /energy/actual. Prediction
versus measurement, committed to twice independently. These five are the
prediction side of an axis this codebase already chose.

Not named environmental.ts on purpose: that names the TOPIC both halves share,
which is exactly what would re-blur the seam operations.ts drew. What separates
them is not subject matter but whether the number is forecast or observed.

**A planned benchmarks.ts was abandoned before any code was written.** Grepping
every /benchmarks caller showed two already live elsewhere: cost.ts holds
unitRates (/benchmarks/unit-rates) and schedule.ts holds benchmarksPullPlanning
(/benchmarks/pull-planning). So the repo had already decided that prefix
distributes by what each method ANSWERS, and a benchmarks.ts would have been
route-prefix grouping contradicting two live placements. benchmarkCosts went to
cost.ts instead, beside unitRates — the same question at a different granularity,
same low/p25/median/p75/high shape. benchmarkResponseRates and
spaceUtilBenchmarks STAYED: no existing mixin owns their question, and inventing
a home for two methods on a guess is what produced this file's UNFILED banner.

Two gates earned their keep. DOC-STRAND caught the extraction stranding
unitRates' doc comment above the inserted block — reunited, not deleted. And the
size ratchet reported 603 where `wc -l` said 602, which is the off-by-one its own
message warns about; the pin took the gate's number.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Portfolio risk heat map — R22-PIPELINE

`GET /portfolio/risk` (`risk_portfolio.py`) grids `risk_board` across the book:
projects down, the five risk engines across (Monte-Carlo schedule risk ·
predictive alerts · EVM · pre-flight gate · overdue coordination), intensity
`3·high + 2·medium + 1·low`. Rendered on Portfolio beside the executive roll-up.

`/portfolio/executive` and `/portfolio/construction` roll up *performance*;
neither could say which risk ENGINE is hot on which project. Cells come from
`risk_board.board` unchanged — same engines, same Monte-Carlo seed — so a cell
and the project's own risk panel cannot disagree. That costs a full board per
project, so the sweep is bounded by `limit` (default 25, clamped 1–100) and
reports `truncated`; the scanned set is a deterministic prefix by name, not the
riskiest projects, because ranking is what the sweep produces and so cannot
choose what to sweep.

AN EMPTY CELL IS NOT A SAFE CELL. A grid of counts renders 0 for two different
facts: this engine looked and found nothing, and this engine could not run.
`board` is fail-open per lane and already separates them, so every cell carries
a `state`; an unmeasured cell carries NO COUNTS AT ALL rather than zeros, and
the UI draws it as a dash. `coverage` reports the split. A clear signal nobody
has a basis for is worse than no heat map — the same lesson as the cap table's
stamped default state, in a second place.

`risk_board.LANES` is new and gated against a REAL board run. `board` reports
coverage under lane keys (`schedule_risk`) while its items carry source strings
(`schedule-risk`); nothing connected the two, and a roll-up must join on both.
`test_risk_portfolio.py` asserts every lane key `board` emits appears in the
table and every `source` its items carry is a value — so a lane added to `board`
alone fails rather than rendering as a column that never lights up.

Both claims mutation-checked: emitting zeros for an error cell, and dropping a
lane from `LANES`, each fail naming the shape. 664/664 backend suites,
2062 web tests, typecheck + lint + build clean.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Review round on #439 — deterministic tie-break, keyboard-operable rows

Two findings from review, both verified real before fixing.

1. STABLE TIE-BREAKER — a bug against this route's own stated contract.
`Project.name` is not unique, and `risk_portfolio`'s docstring promises a
DETERMINISTIC prefix when the sweep truncates. Ordering by name alone leaves
tied rows in whatever order the engine returns, so a tie straddling the `limit`
boundary scans a different project run to run. Now `order_by(Project.name,
Project.id)` — the primary key settles every tie.

Pinned by a test rather than taken on trust: 8 same-named projects at `limit=6`,
asserting the scan takes the four LOWEST-ID rows and not the four first
INSERTED. Mutation-checked — reverting the fix fails it with both id lists
printed. Ids are uuid4 and nothing here can pin one, so a regression escapes
with probability 1/C(8,4) = 1.4%; that number is stated in the test rather than
left implied.

2. KEYBOARD-OPERABLE HEAT-MAP ROWS. `tr.onclick` alone gives keyboard users no
way to open a project. Checking before fixing changed the fix twice:
`.kpi-click:focus-visible` already carries a focus outline in `style.css`, so
the stylesheet was written expecting these rows to be focusable and a
pointer-only handler quietly never delivered it; and `documents.ts` already has
the house idiom — `role="button"`, `tabIndex`, Enter AND Space with
`preventDefault`. Matched that rather than inventing a pattern, plus an
`aria-label` carrying the row's risk count.

Only the row this change added is fixed. The four sibling tables in the same
panel have the identical gap, but they are pre-existing code this change does
not touch; widening into them is the author's call.

Docstrings added to `_score` and `_empty_counts` — the two helpers carrying
ideas worth stating (the intensity weighting, and where a MEASURED zero is
constructed) — and to the two test stand-ins. Matches how `resource_loading.py`
treats its helpers: bare when trivial, documented when the contract is not
obvious.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Cross-project Gantt — R22-PIPELINE

The Programme card now draws a bar per project on a shared span: start, finish,
duration, which project drives the programme finish, and which are named by an
external link.

IT NEEDED NO NEW ENGINE, AND THAT IS THE FINDING. The roadmap recorded a
cross-project Gantt as missing because `schedule_viz.py` is per-project. True,
and not the whole picture: R46's `schedule_portfolio.py` already computes
`project_starts` and `project_finishes` in its one merged pass, and the route
already returned them. `apps/web/src/api/schedule.ts` declared only
`programme_finish`, `project_count` and `external_link_count` — so the dates
reached the browser and were dropped AT THE TYPE BOUNDARY before anything could
draw them. Same class as R37-TESTED-UNWIRED, one layer further out: not a route
without a caller, but a payload without a reader.

Cost of the premise-check: one grep. Cost of believing the entry: a scheduling
engine.

`programmeGantt.ts` holds the geometry as a pure function (7 unit cases); the
panel only paints what it returns.

BARS COME FROM THE MERGED PASS, never each project's standalone CPM — a project
can look comfortable alone and be critical to the programme, and its own run
would show the comfortable answer. Asserted rather than documented:
`test_programme_gantt.py` pins that the FS link pushes fit-out past enabling's
finish, and removing the link fails it with that sentence.

A PROJECT WITH ONLY ONE DATED END GETS NO BAR, and is listed with the reason.
Substituting the programme's own start or finish for the missing end draws a bar
that looks measured and is not — the risk heat map's rule arriving independently
in a second place.

Writing the test also found that an external link names activities by RECORD id:
`wbs` and `ref` are aliases resolved only for a project's own predecessor tokens,
so a link written in WBS terms is refused as "no such activity". Recorded next to
the link that uses it.

2069 web tests (205 files), typecheck + lint + build clean, structural gates
green. Backend suite running.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Review round on #440 — reject normalised dates, require the id separator,
and correct my own wording

Three findings, all verified against the code before fixing.

1. `Date` NORMALISES AN OUT-OF-RANGE DAY instead of rejecting it: "2026-02-30"
parses happily and becomes 2026-03-02, so a bad date drew a bar. Only the month
is range-checked ("2026-13-01" is NaN). `day()` now round-trips through
`toISOString()`. This one bites harder than a generic date nit, because a
normalised date IS an invented one and this module's whole rule is that it does
not draw a bar it cannot measure — the defect was in the guard, not around it.

2. PREFIX COLLISION ON PROJECT IDS. `"p10::A1".startsWith("p1")` is true, so an
external link on p10 flagged p1 as linked and left p10 plain. The separator is
now required. Verified in node rather than reasoned about.

3. MY OWN WORDING WAS FALSE. The roadmap and CHANGELOG said the dates were
"dropped at the type boundary". `HttpCore.json<T>` returns `res.json()` under an
unchecked cast — nothing filters anything at runtime. The dates were in the
parsed response all along; nothing DECLARED them, so no call site could reach
them and none did. Corrected in three places, with the correction recorded in
the roadmap rather than quietly swapped: a plausible-sounding mechanism is
exactly the kind of wrong this file exists to resist.

Both code fixes mutation-checked — reverting each fails its own new test and
nothing else. 10 geometry cases (was 7), 2072 web tests (205 files), tsc and
eslint exit 0, doc gates green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Portfolio resourcing — R22-PIPELINE's last item

`GET /portfolio/resourcing` (`resource_portfolio.py`) sums weekly CONCURRENT
resource demand per trade across projects. `?cap=` flags weeks where one trade
is over-committed across the book and names the competing projects. Rendered on
Portfolio, with the trades on more than one project marked — the only ones that
can be double-booked.

A TRADE ON THREE JOBS IN THE SAME WEEK LOOKS COMFORTABLE ON EVERY ONE OF THEM.
That is what a per-project histogram cannot show and the whole reason for the
endpoint. Proved rather than asserted: two projects at 6 units each are each
under a cap of 8 — verified by calling their own `/schedule/resource-loading?cap=8`
and getting nothing back — while the book reports 12 over the same cap.
Mutation-checked by replacing the cross-project sum with a max, which fails on
the 12-vs-6 assertion.

"BY DEPARTMENT" WAS THE WRONG SHAPE, AND THE SCHEMA SAYS SO.
`resource_assignment.trade` is labelled "Trade / discipline", and "department"
appears nowhere in the backend except a comment in `rooms.py` and a
fire-department scope clause. A department axis is a PRODUCT DECISION — what is
a department that a trade is not? — not a filter over data we hold. Raised in
the roadmap rather than invented: a dimension nobody has defined cannot be
reported honestly. The portfolio axis was the half that mattered, and it needed
no new field.

FIDELITY IS REPORTED, NOT BLENDED. A project with no assignments falls back to
activity `crew_size`, which is a crew count and not a resourced plan, so every
row carries its `source` and `fidelity` gives the split. The heat map's rule one
step along: do not let a lower-fidelity value wear the costume of a
higher-fidelity one.

The two `over_allocation` shapes are NOT interchangeable and both docstrings say
so: this one caps per trade across the book, `resource_loading`'s caps one
project's total weekly units. The test says it too — its fixture puts the
single-project trade on its own project for exactly that reason.

A GATE CAUGHT SOMETHING ON THE WAY IN, AND IT WAS A WORD. The field
`fidelity.resourced` put the substring `sourced` into the web source, and that
is the leaf of `/schedule/eot/sourced`, so `test_route_reachability` reported a
frozen-uncalled route as called. `strip_comments` was no help — the collision
was in an identifier, not prose. Renamed to `assigned`, which names its source
rather than restating an adjective. Second instance of a class that gate already
records; the note there now explains why the matcher is not the thing to change.

2072 web tests, tsc + eslint + build clean, 12 structural gates green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Roadmap truth pass + R39-DECOMP-VIEWER (17)

TWO STALE CLAIMS CORRECTED, both found by testing the entry against the tree.

R38-SYNC-2D3D's stated defect is fixed end to end. The entry said the pipeline
"discards element identity at bake time" and that "nothing in a plan can name
what it draws". `_bake_uncached` returns (guid, ifc_class, mesh) and its own
docstring credits R38-PLAN-IDENTITY; `cut_baked_guided` emits (guid, class,
polyline) with a PRODUCTION caller in the plan renderer; the SVG carries
data-guid and planPane.ts selects on it. The entry described two functions
accurately and drew the wrong conclusion because it never looked for a third.
What actually remains: it claims three open children and names none.

CLAUDE.md's viewer numbers were both stale — "twenty-eight commits" and "3,444
lines" are now 67 and 2,570. Unlike the Node and Python drifts that file already
records, this one moved in the direction that STRENGTHENS its argument, which is
the hardest kind to notice: a number that decays toward the conclusion it
supports never looks wrong.

R39-DECOMP-VIEWER (17) — field verification out of app.ts (2,571 -> 2,508).

app.ts is not a class, so REL-4's "grep the this. refs first" rule has no this.
to grep: the file is ONE 2,445-line function and everything in it is a closure.
The equivalent is how many SIBLING closures a candidate captures, and over all
fourteen candidates >=25 lines exactly ONE captured zero. buildToolsPanel
captures 14, handleKey 12, selectByGuids 6 — every other move would have been the
callback bag REL-4 warns about. Four of five free variables already travelled on
the typed ViewerCtx, so the deps object is that context narrowed.

THE NARRATIVE-CHAIN GATE REFUSED THE FIRST RATCHET ENTRY, CORRECTLY. The previous
entry ended at 2,571 and the file measured 2,570 — one line had left with no
slice recording it, the drift the roadmap cell already documents from another
lane. The entry now runs 2,571 -> 2,508 and names the stray rather than starting
at a number nobody can reproduce. Ratchet mutation-checked at 2,507.

2072 web tests, tsc + eslint + build clean, 8 structural gates green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* SCALE-SEAM (102) — counterparty risk, client.ts 603 -> 589

`prequalScores`, `coiExpiry` and `lienExposure` out to
`apps/web/src/api/counterpartyRisk.ts` — which trade partner is a risk on this
job, and why: are they qualified, are they insured, and do we owe them enough to
be liened.

THE WITNESS IS THAT THE SEAM DISAGREES WITH THE ROUTE PREFIX. Two sit under
/prequal/ and one under /payapp/lien-exposure, so a prefix grouping would have
SPLIT the set — while all three return per-counterparty rows carrying a verdict
about that counterparty: risk_band + flags, days-to-expiry, exposure +
vendors_at_risk.

That is the affirmative form of a rule this repo has only recorded negatively:
(85) rejected "they are all multipart uploads", (89) "they are all module
records", annotate.ts "they all call editIfc" after measuring 24 recipes across
nine categories. A shared mechanism is not a question. Here the mechanism argues
AGAINST the grouping and the shape of the returns argues for it, so the evidence
is not something a name could have produced.

benchmarkResponseRates sits immediately above them and STAYED: it returns
RFI/submittal turnaround and names no counterparty at all — it measures how
responsive the process is. Adjacency is not a relationship, which REL-4 recorded
three separate times this cycle.

Found on the way out: an orphaned PrequalScores type import, the same residue
slice (101) left with EnergyResult.

Ratchet 603 -> 589, mutation-checked at 588 (both the growth assertion and the
history-chain assertion fire). 2072 web tests, tsc + eslint clean, doc gates green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Review fixes on #442, and a gate for the number that keeps drifting

Four CodeRabbit findings, all verified against the tree first. The second was
self-referential and is the interesting one.

This PR corrected CLAUDE.md's stale app.ts line count from "3,444" to 2,570 --
and then R39-DECOMP-VIEWER (17), in the same PR, took the file to 2,508. The
paragraph diagnosing numbers that decay toward the conclusion they support
decayed toward its own conclusion before it merged, and a review bot found it
rather than the author.

So test_claude_md_gates.py now checks that number against the ratchet. The
existing gate asks whether a cited FILE exists; this asks whether a cited NUMBER
is still true. It is cheap only because the value is not really CLAUDE.md's to
hold: test_file_sizes.py already pins the same file at an exact size, so the
prose is a COPY of a gated value, and a copy is what drifts. Mutation-checked
both ways -- a wrong figure fails, and a REWORDED SENTENCE fails too rather than
passing on two Nones, which is the vacuous-green failure that file's own header
calls worse than no gate at all.

R38-SYNC-2D3D is CLOSED, with its children named. The entry claimed three of
four children were open and named none of them. Re-derived by grepping the tree
rather than reading the file that was already wrong: R38-SYNC-SELECT,
R38-SYNC-VIEW, R38-PLAN-TRANSFORM and R38-PLAN-IDENTITY, and
docs/roadmap-completed.md carries a check for EACH. The 2026-08-10 un-archive
was mechanically right -- a lane row pointed at nothing -- and then inherited
the restored text's open count as though the restore had verified it. Nothing
had: R38-PLAN-IDENTITY was marked done that same day, in the archive the entry
was being pulled out of. Un-archiving restores an entry's TEXT, not its truth.

NAMING THOSE CHILDREN MADE THEM ITEMS, AND THE GATES SAID SO. Four bold item
codes in roadmap.md put three new orphans in roadmapLanes.test.ts and a stale
open-vs-implemented pair in roadmapStale.test.ts. The fourth escaped only
because its line happened to contain a check mark in prose. All four now carry
an explicit marker -- passing by accident and passing by construction look
identical until something moves.

Also: completed the verbless counterparty-risk changelog entry, and gave the
bare `wc -l` in CLAUDE.md's re-measure command its argument, since an
instruction to verify that hangs on stdin is one nobody runs twice.

Verified: 2072 web tests, tsc + eslint clean, roadmap lane/stale gates green,
citation gate green and mutation-checked twice.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* SCALE-SEAM (103) — acceptance gates, client.ts 589 -> 572

permitReadiness, diligenceReadiness, handoverAcceptance and validate ->
acceptanceGates.ts: "will an outside party accept this project, and what is
blocking it".

NEITHER THE ROUTE NOR THE AUDIENCE PRODUCES THIS GROUPING. The four routes are
/permit/readiness, /diligence/readiness, /handover/acceptance and /validate --
four different prefixes, so a prefix grouping takes one each and the set never
forms; the shared leaf word "readiness" reaches only two of the four. The
deciding parties are an AHJ, an investor, an owner and an IDS checker -- four
different audiences, so grouping by reader fails too.

What forms it is the RETURN SHAPE: each collapses the whole project to a single
accept/refuse verdict (verdict / go / accepted / status:"pass"|"fail") and then
enumerates what withholds it. (102) was carried by a prefix that actively
DISAGREED with the seam; this one by a vocabulary that says nothing at all --
four names sharing no words can still be one question, which is the inverse of
the error (85), (89) and annotate.ts each recorded, where a shared mechanism
looked like a shared question.

THE TWO EXCLUSIONS DID THE WORK. spineTraceability is the closest miss -- same
domain, adjacent in the file, equally project-scoped -- and returns
coverage/gaps/chain with NO verdict field at all: it maps completeness for a
human rather than deciding acceptance. editPrecheck DOES return a verdict, but
judges a PENDING ACTION ("may I run this recipe with these params"), is remedied
by changing the params you are about to submit, and sits beside addCurtainWall
as the precheck for editIfc.

ONE FALSE POSITIVE, RECORDED BECAUSE IT WAS INVISIBLE. A scan for verdict-shaped
returns also flagged collabSnapshot -- but the match came from the doc comment
introducing permitReadiness, the NEXT method. A method-body splitter that runs
to the next header swallows the comment belonging to that header, so the
population silently inherits its neighbour's vocabulary; a count of six looked
entirely checked. Only reading each candidate caught it.

Also files handoverAcceptance, which an earlier slice had parked under an
explicit UNFILED note asking for it to be placed by what it ANSWERS rather than
by what it sits next to. That note is narrowed to two entries, not deleted --
the other two are still genuinely unfiled, and a note that silently loses
entries is how earlier slices lost methods.

THE DOC-STRAND GATE CAUGHT A DEFECT IN THIS SLICE'S OWN NEW FILE: a /** */ doc
comment on the Ctor type sat directly below the module header, which that gate
reads as a stranded comment -- the header carrying the whole witness was one
line from reading as documentation of a type alias. It is a // comment now,
which is why counterpartyRisk.ts has none there either. The fast checks (tsc,
eslint) were clean while this was broken; the suite is where it lived.

Verified: 2072 web tests / 205 files, tsc + eslint clean, whole-tree ruff clean,
ratchet mutation-checked at 571 (both the growth and chain-end assertions fire),
48-entry narrative chain unbroken, test_route_reachability + test_reachable +
test_import_cycles + test_doc_substance + test_claude_md_gates + test_ruff_scope
+ test_declared_imports green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

---------

Co-authored-by: Claude <noreply@anthropic.com>

* SCALE-SEAM (95) — element state: two read/write pairs, and why the matrix loses

Moves `lodSummary`/`setLod` and `phasing`/`setPhase` out of `client.ts` into
`api/model.ts`. They answer one question — *what state are the model's elements
in, and set it?* — and `client.ts` goes 727 -> 711, 76 methods above the STAYING
banner.

The grouping is derived, not asserted:

- identical return shape `{ total, <x>ed, prop, counts: Record<...> }`;
- both writers are `(pid, guids, <enum>, publish) -> editIfc`;
- both readers are consumed by `viewer/tools/modelStatePanels.ts` (251, 316);
- both writers sit unwired and *adjacent* on `clientCallers.test.ts`'s UNCALLED
  allowlist;
- `model.ts` already owned `/model/lod/census`, `/lod/handover-readiness` and
  `/lod/assessment`, while the base distribution `/projects/{pid}/lod` was left
  behind in `client.ts` — `lodSummary` was a sibling separated from its family.

`authoring_matrix.py` DISAGREES and is recorded as the losing vote rather than
elided. It files `set_lod` under `data` and `set_phase` under `lifecycle`,
because it categorises by the IFC output each recipe writes — an LOD stage tag
against `Massing_Phasing.Status`. Different property sets, same question, which
is (89)'s "storage is a HOW" trap. This is the first slice where the matrix has
been wrong after being right three running.

It also MEETS (94)'s objection rather than overriding it: that slice declined
`setPhase` because taking the writer alone would have stranded `phasing()`, the
reader/writer split (87) had to undo. Both halves move together here.

The four names are added to `surface.test.ts` because its floor is a slack
ratchet (788 actual vs 751 floor) — the count alone would not notice a loss —
and because the UNCALLED allowlist is about call sites, not the surface.

Verified: tsc 0, lint 0, `vitest run src/api` 27 files / 119 tests, build 0,
`test_file_sizes.py` / `test_claude_md_gates.py` / `test_roadmap_status.py` /
ruff all 0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* SCALE-SEAM (96) — the as-built question's aggregate reader, and a witness that actually bounds

Moves `lod500`, `setManufacturerInfo` and `attachOmDocument` out of `client.ts`
into `api/model.ts`, rejoining `verifyAsbuilt` and `recordAsbuiltDimension`
which (94) moved. `client.ts` goes 711 -> 698, 73 methods above the STAYING
banner.

TWO BOUNDING WITNESSES, derived independently, agreeing:

- `openAsBuiltPanel` in `viewer/tools/modelStatePanels.ts` calls exactly five
  API methods — read off that function's brace closure rather than grepped for,
  so it is the closure of a scope and not a sample. Two of the five were
  already in `model.ts`.
- The reader's own response type names its writer set field by field:
  `verified`/`by_method` from `verify_asbuilt`;
  `with_dimensions`/`dimensions_out_of_tolerance` from
  `record_asbuilt_dimension`; `with_manufacturer`/`with_serial` from
  `set_manufacturer_info`; `with_om_docs`/`om_documents` from
  `attach_om_document`. The backend route says it in prose: "Stamp elements
  with the `verify_asbuilt` recipe."

A reader whose response type enumerates its writers is a DERIVED population.
After eight slices of sampling, that is the first grouping witness here that
bounds a set instead of illustrating one.

WHAT CORROBORATES IS NOT WHAT BOUNDS. `test_lod500.py` reaches exactly three
recipes — `attach_om_document`, `set_manufacturer_info`, `verify_asbuilt` — and
OMITS `record_asbuilt_dimension`, which is unambiguously in this family. It
agrees with the answer without being able to establish it. Three slices claimed
"and no others" off a test file and were wrong all three times.

NOT CLAIMED, and said in the header, the pin, the changelog and the roadmap
rather than only in review: `attachDocument` stays in `client.ts`, takes a
`purpose` parameter, and `asbuilt_summary` counts ANY purpose-tagged document
reference — so "every writer of `with_om_docs` moves here" is false. The field
map is of the recipes each field was designed around, not of everything that
can set it.

Two sources disagree and lose for the same reason: `attach_om_document` is a
purpose-tagged wrapper of `detailing.attach_document`, and
`authoring_matrix.py` files it and `set_manufacturer_info` under `data`. The
first is a shared HELPER, the second a STORAGE bucket — the groupings (89) and
(90) each had to reject. The matrix is the losing vote twice running after
being right three times.

Also fixes the extraction helper: it terminated its brace count on the method
signature line, so a signature wrapping across two lines with no opening brace
on the first read as a 3-line method. `attachOmDocument` is 6.

Verified: tsc 0, lint 0, `vitest run src/api` 27 files / 119 tests, build 0,
ruff (the CI command, from `services/api`) 0, and `test_file_sizes.py`,
`test_claude_md_gates.py`, `test_roadmap_status.py`, `test_ruff_scope.py`,
`test_reachable.py` all 0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* SCALE-SEAM (97) — the undo stack, and a destination that looked right and was not

Moves `editHistory`, `editUndo` and `editRedo` out of `client.ts` into
`api/authoring.ts`. `client.ts` goes 698 -> 687, 70 methods above the STAYING
banner.

WHY THAT MIXIN: `editIfc`, already there, is the PUSH they pop. `authoring.py`
records the pre-edit version on every `/edit` call "so this edit can be undone",
`_restore_version` pops that stack, and `edit_history.state()` reads its depths.
One stack, and the operation that fills it was already in this file.

The types agree: both writers return `{restored, state: {can_undo, can_redo}}`,
and `state` is `editHistory`'s own return type minus the depths — the writers
hand back the reader's answer. That is a type-level relation, not the shared
`/edit/` prefix. The prefix is real and is deliberately not the argument, since
a route prefix is exactly what the verification slice was caught grouping on.

A HYPOTHESIS TESTED AND WITHDRAWN, which is the part worth keeping. "Undo
restores the prior model version" makes `model.ts` the obvious home — it owns
`modelVersions`, `versionDiff`, `versionCostDelta`. It is the wrong home: those
read `/projects/{pid}/versions` out of `bim.py`, while undo pops a DIFFERENT
stack, the `edit_history` sidecar, which `recipe_log.py` describes as a list of
file paths with "No recipe, no parameters, no actor". Two stacks, one word — and
the word is what made the wrong answer look obvious. Second withdrawal of a
plausible destination after checking it, after (93) withdrew (92)'s `HttpCore`
forecast.

THE BOUND IS WEAKER THAN (96)'s AND IS STATED THAT WAY. `app.ts`'s S4 block
wires `refreshUndo` (calling only `editHistory`) and `doUndoRedo` (calling only
`editUndo`/`editRedo`), so the union is exactly these three — but that unit is a
block delimited by reading, not a closure the braces define. It corroborates; it
does not bound. Not every set has a witness as strong as the last one's, and
promoting a block to a closure would be this sequence's own recurring defect.

Verified: tsc 0, lint 0, `vitest run src/api` 27 files / 119 tests, build 0,
ruff (the CI command, from `services/api`) 0, and `test_file_sizes.py`,
`test_claude_md_gates.py`, `test_roadmap_status.py` all 0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Correct the undo/redo republish docs — all three sites, not just the flagged one

CodeRabbit flagged `editUndo`'s docstring on #414: it says "restore the prior
model version + republish" unconditionally, but `publish` defaults to true and
can be false. Verified against the backend — `_restore_version` guards the
republish with `if publish:` — so the claim is wrong whenever a caller passes
`publish: false`.

Grepping every site of that wording found the same unconditional claim in THREE
live places, not one:

- `apps/web/src/api/authoring.ts` — `editUndo` (the flagged one)
- `services/api/src/aec_api/routers/authoring.py` — the `/edit/undo` route
- `services/api/src/aec_api/routers/authoring.py` — the `/edit/redo` route

All three now say republishing happens only when `publish`. The remaining hits
are UI button labels, where the call site never passes the flag so republish
really is unconditional, and historical CHANGELOG entries; both are correct as
written and are left alone.

Also fixes the same defect's other half in the same five lines: the declared
return type omitted `publish`, which the backend adds as `"running"` when it
republishes. Correcting the prose while leaving the type silent about the same
conditional would be the half-applied fix this sequence has twice been caught
making.

Verified: tsc 0, lint 0, `vitest run src/api` 27 files / 119 tests, build 0,
ruff (the CI command, from `services/api`) 0, `test_file_sizes.py` 0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* SCALE-SEAM (98) — detailing carriers, and a field map total over one module but not the codebase

Moves `elementDetailing`, `classify`, `applyDetailingRules`, `validateDetailing`
and `attachDocument` out of `client.ts` into a new `api/detailing.ts`.
`client.ts` goes 687 -> 665, 65 methods above the STAYING banner.

WHAT THEY ANSWER: what informational carriers are attached to this element,
write them, and which are missing?

THE WITNESS IS A 1:1 AND TOTAL FIELD-TO-WRITER MAP, the shape (96) established.
`element_detailing` walks `HasAssociations` and branches on exactly two
relationship types, and `detailing.py` holds exactly two writers, one per
response array:

  classifications[]  <-  classify        (IfcRelAssociatesClassification)
  documents[]        <-  attachDocument  (IfcRelAssociatesDocument)

The map is read out of the reader's own body, not matched on names. The other
two methods are those same writes automated and audited: `applyDetailingRules`
runs the condition-to-content rule set and writes both carrier kinds,
`validateDetailing` reports elements a rule applies to that lack the code.

TOTAL OVER THE MODULE, NOT THE CODEBASE, and the difference is the claim.
`attachOmDocument` — moved to `model.ts` in (96) — wraps the SAME
`detailing.attach_document` and also lands in `documents[]`, so "these are all
the writers of this reader's fields" is false. That overlap was recorded when it
moved, which is why it was on hand to qualify this slice rather than being found
in review.

ADJACENCY AGREED WITH THE ANSWER AND IS NOT EVIDENCE FOR IT. These five were
contiguous in `client.ts`; unlike (95), where non-contiguity was the whole
argument, a positional split would have found this set too. Stated precisely
because it looks like support.

ALSO RECORDED: `api.classify()` has no call site — `detailingSection.ts` drives
the recipe through the generic `authorAndReload` path, bypassing the typed
method, and `clientCallers.test.ts` counts it reached because it matches bare
string literals as well as calls. That looseness is deliberate per that file's
own docstring, so it is a limit of the gate rather than a defect in it.

The new mixin needs `editIfc`, so it declares `NeedsEditIfc` and composes
outside `withAuthoring`; `compositionOrder.test.ts` gains a fourth assertion.
MUTATION-CHECKED: relaxing the constraint to `Ctor<any>` produces "TS2578:
Unused '@ts-expect-error' directive" on exactly the new line, so it fails for
the reason claimed rather than merely passing.

The extraction removed 27 lines and the banner plus import added 5 back — caught
by the ratchet, not by me, the same way (94) found its own banner growth.

Verified: tsc 0, lint 0, `vitest run src/api` 27 files / 119 tests, build 0,
ruff (the CI command, from `services/api`) 0, and `test_file_sizes.py`,
`test_claude_md_gates.py`, `test_roadmap_status.py` all 0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* SCALE-SEAM (99) — the content shelf, and a destination header that was wrong until now

Moves `contentCatalog`, `placeContent` and `importContent` out of `client.ts`
into `api/authoring.ts`. `client.ts` goes 665 -> 648, 62 methods above the
STAYING banner.

WHAT THEY ANSWER: what pre-made content can I place, and place it?

THE WITNESS IS A ROLE-FOR-ROLE PARALLEL with the family shelf already in that
file, read off the signatures rather than the shared noun:

  catalog reader    familyCatalog()  {count, categories: Record<..>}
                    contentCatalog() {count, note, groups: Record<..>}
  placer            placeFamily(pid, family, position)
                    placeContent(pid, category, point, name)
  multipart import  async importFamilies(pid, file, ..)
                    async importContent(pid, file, opts)

Three roles, three methods each, matching shapes and arities. A parallel between
two method TRIPLES is structural; "both are shelves" would have been a shared
word, which is the grouping (88) and (89) each had to reject.

THE DESTINATION'S OWN FIRST LINE WAS WRONG UNTIL THIS COMMIT. `authoring.ts` has
described itself as holding "the family/content shelf" while containing ZERO
content methods — the word's only other appearances there are an HTTP header and
a sentence about IFC *type* content. The docstring stated an intended scope as
fact.

That is recorded as corroboration that was FALSE, not as evidence. A header
agreeing with the answer is worth nothing until someone checks whether it is
true, and this one had been wrong for as long as it had existed. It is the
smallest possible instance of the drift the project instructions keep warning
about.

Verified: tsc 0, lint 0, `vitest run src/api` 27 files / 119 tests, build 0,
ruff (the CI command, from `services/api`) 0, and `test_file_sizes.py`,
`test_claude_md_gates.py`, `test_roadmap_status.py` all 0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* SCALE-SEAM (100) — the element-connection pair, and a destination named at its real strength

Moves `elementConnections` and `connectElements` out of `client.ts` into
`api/model.ts`. `client.ts` goes 648 -> 642, 60 methods above the STAYING
banner.

WHAT THEY ANSWER: what is physically joined to what, and record a joint?

THE PAIR IS BOUND BY THE BACKEND NAMING ITS OWN WRITER, the (96) shape: the
`/element-connections` route docstring reads "Author edges with the
`connect_elements` recipe (POST /edit with {guid_a, guid_b})". Reader and
writer, one relationship type (IfcRelConnectsElements), both marked B5.

THE DESTINATION ARGUMENT IS WEAKER THAN THE PAIRING ARGUMENT AND IS LABELLED SO.
`model.ts` owns `modelGraphStats`, whose `by_rel` counts the IFC relationship
graph BY RELATION — IfcRelConnectsElements being one — and `graphNeighbors`,
which walks it. So this pair is one relation of a graph the file already reads,
plus its authoring verb. That is a SPECIALISATION, not an identity: the graph
methods are generic traversal over every IfcRel*, these two are one relation
with a verb attached. The pairing is evidenced; the placement is a judgement,
and collapsing the two into one confident sentence is the overstatement this
sequence keeps catching.

TWO CANDIDATES REJECTED ON CHECKABLE GROUNDS. `connections.ts` is the trap: it
is DATA-SOURCE connections — SQL, ACC, Procore — sharing nothing with this but
the English word, and it is the file a name-based search lands on first. (97)
found two version stacks behind one word; this is the same collision in a
destination rather than a source. `elements.ts` holds element ATTRIBUTES and
views, and a relationship between two elements is not an attribute of either.

`addBasePlate`/`addShearTab` did not come despite sharing `connections.py` with
these: a backend module is a HOW, the grouping (89) had to reject, and those two
author PHYSICAL assemblies rather than relationship edges.

FOUND WHILE DERIVING, RECORDED NOT FIXED: `add_connection_assembly` (B5,
IfcRelConnectsWithRealizingElements) has no client method anywhere in
`apps/web/src` — a backend recipe with no web exposure, the class (93) recorded
for three MEP recipes.

Verified: tsc 0, lint 0, `vitest run src/api` 27 files / 119 tests, build 0,
ruff (the CI command, from `services/api`) 0, and `test_file_sizes.py`,
`test_claude_md_gates.py`, `test_roadmap_status.py` all 0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* R22-ENTITLEMENT ⑤ — an agency review comment becomes an RFI somebody owns

`RecordComment` had NO outward link of any kind. An agency's comment on an
`entitlement` or `permit` was a text blob at the end of a thread: readable, and
impossible to assign, track or close. ④ made comments survive a revision — the
INBOUND half of "round-tripping"; this is the outbound half the ring entry still
listed as remaining.

`POST /projects/{pid}/modules/{key}/{rid}/comments/{cid}/promote` mints a Topic
carrying the comment text, the source record's ref and its `element_guids`, and
writes a back-link on the comment.

THE BACK-LINK IS THE IDEMPOTENCY. A second promote 409s instead of minting a
duplicate RFI — the failure mode a promote button produces on every
double-click. Both load-bearing assertions in `test_comment_promote.py` were
MUTATION-CHECKED: removing the 409 guard makes one comment mint two RFIs (the
failure output shows both `comment.promote` activity entries), and removing the
back-link write drops `topic_id` from the comment.

Follows `promote_markup` rather than inventing a second idiom — mint, carry
provenance, link back, 409, audit.

REACHABLE, NOT MERELY BUILT: the control renders beside the comment and is
replaced by "→ RFI raised" once promoted, because a button whose only remaining
outcome is a 409 is worse than no button.

Adding it turned `register.ts`'s extraction ratchet red, and the remedy is the
one that file states — extraction, never headroom. The comment thread, composer
and new control came out to `portal/register/recordComments.ts` (2,516 -> 2,505,
pin lowered with it). A genuine leaf: it touches the record's comments, the API
and a reload callback and nothing else on the class, and the directory already
holds three leaves extracted the same way.

WHAT THE PREMISE-CHECK FOUND, and it is why this slice exists. The entry's
"Remaining:" line named two things and contradicted itself on one — it listed
submittal packages flatly while the note above it said the inbound half had
shipped. Measured: the inbound view is real, but assembling a package to send is
not, because `modules/transmittal/module.json` types `items` as a textarea and
`to_company` as plain text. Package contents are prose no machine can resolve
back to the records named, and the recipient cannot be the agency an
`entitlement` names, since that is free text too. That is a SCHEMA question, not
a workflow one — which is why reading the workflow surface kept reporting it
done. The roadmap now says that instead of the flat line.

Also corrected: the roadmap's argument against picking SCALE-SEAM quoted
`client.ts` at 2,837 lines. It is 642 — copied forward through every slice since,
the exact drift the rows beside it document twice.

Verified: tsc 0, lint 0, build 0, `vitest run src/portal src/api` 50 files / 275
tests, ruff (the CI command, from `services/api`) 0, and `test_comment_promote`,
`test_modules`, `test_topic_lifecycle`, `test_reachable`, `test_declared_imports`,
`test_ruff_scope`, `test_file_sizes`, `test_claude_md_gates`,
`test_roadmap_status`, `test_doc_substance`, `test_alembic_single_head` all 0.
Full 660-suite running as a cross-check.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* R22-ENTITLEMENT ⑤ review: promotion claims the comment atomically, and a blank one no longer 500s

Two findings on #434, both reproduced before fixing and both mutation-checked after.

**A whitespace-only comment 500s on promote.** The comment route takes
`text: str = Body(...)` with no min-length, so `{"text": "   \n  "}` is a 201.
Promoting it ran `.strip().splitlines()[0]` over an empty list — IndexError.
The `or f"{key} {ref} review comment"` fallback written for exactly this case
had never been reachable at all: when the list is non-empty its first element
is never blank, so the `or` arm could not fire. The guard makes it live.

**Promotion idempotency was not atomic — and the damage is worse than a
duplicate.** `SessionLocal` is `expire_on_commit=False`, so a request that read
the comment before a concurrent promote committed keeps seeing a null back-link
for as long as it holds the session; the `if cm.topic_id` guard reads that stale
copy. A plain assignment then let the later writer overwrite the back-link,
minting a second RFI AND orphaning the first, whose Topic no comment pointed at
any more. The claim is now a conditional `UPDATE ... WHERE topic_id IS NULL`:
under Postgres read-committed the loser blocks on the winner's row lock and
re-evaluates the predicate against the committed row; under SQLite the writes
serialize to the same effect. Rolling back discards the Topic flushed a moment
earlier, so a losing promote leaves nothing behind.

The race test is deterministic rather than timing-dependent — the loser reads,
the winner commits, the loser proceeds from its stale identity map, which is the
production sequence. Mutation-checked both ways: restoring the unguarded index
raises IndexError, restoring the plain assignment fails "a stale-read promote
must be refused, not duplicated".

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* R24-REPORTS-BY-MOMENT — a finished pack can be sent, not only downloaded

`POST /projects/{pid}/jobs/{job_id}/deliver` emails any finished job's artifact
to named recipients, surfaced as **Send** beside **Download** in the job tray.

**The roadmap named the wrong blocker, one layer too high.** The entry said
making a pack a scheduled deliverable "still wants a delivery surface and SMTP".
Both already existed when that was written: `mailer.py` sends real mail (stdlib
smtplib, a Settings "Test connection" button), and `POST …/notifications/digest`
is a working assemble-then-send surface returning a per-recipient status map.
What was actually missing was one size smaller — **the mailer could not carry a
file**. That is why the entry sat: the two things it named were present, so every
look confirmed it and nobody checked the layer below.

`build_message` gained attachments. The ORDER is load-bearing: `add_alternative`
must run before `add_attachment`, or the html body lands inside the mixed part —
Python's EmailMessage refuses outright ("Cannot convert mixed to alternative"),
which the test asserts rather than assumes.

Refusals mirror the download route exactly (404 wrong project, 409 while
queued/running, 404 with no artifact) so a caller does not learn two answers to
"is this artifact ready", plus two of delivery's own: an empty recipient list is
422 rather than a silent success, and over 15 MB is 413 rather than a
per-recipient error from a server that would have bounced it anyway. An
unconfigured deployment returns 200 with every recipient `disabled`, so the UI
reads `smtp_configured` before claiming a send. The delivery is audited — a file
leaving the system is what an audit log is for.

**Not shipped, deliberately: the SCHEDULED half.** There is no scheduler of any
kind in this tree — no APScheduler, no croniter, no cron — so the existing digest
is admin-triggered and nothing runs on a date. Choosing in-process versus
external cron hitting an endpoint is a deployment decision with different
operational consequences, not a wiring task. The roadmap now says that instead of
naming two things that already ship.

Mutation-checked, four ways on the route and one on the tray: dropping the
empty-recipient refusal reproduces the silent success it exists to prevent (200
with `"results":{}`); dropping the size cap admits 15 MB + 1; ignoring
attachments loses the file; attaching before the alternative raises; and ungating
Send from `hasArtifact` offers it on a job with nothing to send.

The client-caller gate did its job here — it failed the build because
`deliverJobArtifact` had no screen, which is what drove the job-tray wiring
rather than shipping another endpoint nobody can reach.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Review round on #435: five findings, all verified real, all fixed

**1. A malformed recipient aborted the whole delivery (Major).** `send_email`
built the message BEFORE its try block. `EmailMessage` rejects a header value
containing CR/LF with ValueError, and this function is documented to never raise
— so one bad address raised out of the loop after earlier recipients had already
received the artifact and before the audit row was written, leaving the record
disagreeing with what happened. Construction moved inside the protected flow;
a bad address is now that recipient's "error" and nobody else's. Also built (and
discarded) on the unconfigured path, so a malformed address does not become
visible only in production.

**2. STARTTLS presented an unverified context (Major, CWE-295).** The finding's
stated reason was wrong — it said "Python 3.9 uses an unverified context" and
this repo is on 3.12 — but the conclusion holds on 3.12 too: measured,
`ssl._create_stdlib_context()` reports verify_mode=0 and check_hostname=False,
so the artifact and the SMTP password went up with no certificate check. Both
call sites now pass `ssl.create_default_context()`.

**3. The size cap ran AFTER materialising the object (Major).** `storage.get`
pulls the whole artifact into memory and `len(data)` checked it afterwards, so
the memory was already spent on exactly the payload being refused — and
concurrent callers multiply it. `storage.size(key)` already existed; the check
now runs before the read.

**4. Recipients were unbounded and undeduplicated (Major, CWE-770).** Each
address is a synchronous SMTP conversation with a 15-second timeout, so an
unbounded list occupies a worker for hours. Now de-duplicated case-insensitively
(preserving caller order) and capped at 25 — as a 422 refusal, not a silent trim,
because quietly dropping recipients is the same silent-success failure the
empty-list 422 exists to prevent.

**5. The test stole the runner's STORAGE_DIR (Minor).** `run_tests.py` assigns
`STORAGE_DIR=./_storage_{test}` and sweeps exactly that path; the test overwrote
it, so its 15 MiB blob landed somewhere the runner does not own. That is what the
suite footer's "dir(s) this runner does not own" counts, and the stray directory
was sitting on disk at 61 MB. Now `setdefault`.

Every fix is mutation-checked. Restoring the pre-fix code fails with: build
outside the try -> AssertionError on the per-recipient result map; size-after-read
-> "materialised <key>" from a patched storage.get, which proves the object was
pulled in; no cap -> 26 recipients accepted; no dedup -> a@ and A@ both served;
bare starttls() -> "called with no context — that context does NOT verify",
asserted through a fake SMTP that captures what is actually passed rather than by
reading the source.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Second review round on #435: the port fix is the root cause my first fix missed

Three new findings on the fix commit. Two were real defects, one is a design
question answered rather than obeyed.

**A mistyped SMTP port escaped the no-raise boundary (Major) — and this is the
SAME defect class the previous commit fixed, one line above the guard.** That fix
moved `build_message` inside the try and left `int(AEC_SMTP_PORT)` outside it.
Settings are stored as arbitrary strings (`settings_store.set_value(db, k,
str(v))`, no numeric validation), so a typo in the Settings form raised
ValueError straight through a function documented never to raise, aborting the
delivery loop before its audit row — exactly the failure the CR/LF fix was for.
Treating the instance instead of the class is what left it. The whole prologue is
now inside the boundary: this function returns a status for ANY input,
configuration included.

**A recipient could forge log lines (Minor, CWE-117).** Both exception handlers
logged `to` with `%s`, so CR/LF in an address writes literal newlines into the
stream and a recipient can append a plausible-looking record of its own. Now
`%r`, which escapes them — the value is still reported, never as its own line.
This one was introduced by my previous commit, not found in old code.

**Cleartext SMTP auth: warned, not refused — deliberately.** The finding asks to
reject `send_email`/`smtp_test` outright when `AEC_SMTP_TLS=0`. That is a
documented deployment choice for a self-hosted product relaying through localhost
or a trusted internal MTA, where cleartext is not an exposure; hard-refusing
would break those installs to protect against a risk they do not have. What is
not defensible is doing it silently, so a credential sent without TLS now logs a
warning naming the setting and the remedy. The password is never logged, and the
test asserts that.

Mutation-checked: %s in place of %r puts the forged line back in the stream;
moving the port parse back outside the try loses the "error" status; removing the
warning loses the cleartext notice. The password assertion was rewritten after it
passed for the wrong reason — the fixture used "p" as the password and the
haystack was full of the letter p, so it now uses a distinctive value.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Only committed capital owns anything — cap table and waterfall

`capital.cap_table` summed `commitment` across every investor whatever their
workflow state. A `prospect` carrying a $10M interest and $0 contributed took
50% of a $10M cap table and halved a real LP from 60% to 30%. It did not stop at
display: `distwaterfall` allocates `share = lp_total * (commitment / lp_commit)`
off these rows, so the prospect drew **$1,818,181.82 of a $2M distribution**
while the committed LP got $181,818.18.

**The obvious filter is wrong on its own, which is why this took a guard.**
`investor` declares `initial: prospect` and every record is stamped with it at
creation, so on a project where nobody ran the `commit` transition EVERY investor
is a prospect and filtering empties the cap table. The roadmap records this was
implemented once and made `test_distwaterfall` return 0.0 instead of $2,000,000.

`workflow_in_use` separates two readings of the same value: **a default state is
not a signal.** Until some investor has moved off the stamped initial state,
`prospect` means "nobody used the workflow" and everyone counts, exactly as
before. Once one has, `prospect` means "not committed" and the state is evidence.

Of the three options the roadmap put to the owner, this is (c). (b) — keying on
`contributed > 0` — was rejected as a domain error: in an uncalled fund an LP
with a signed commitment and no contribution yet is normal, and that rule would
zero out real LPs who simply have not been called. (a) — changing the initial
state — needs a data migration and rewires the default entry path.

Prospect rows are never dropped: they stay visible at 0%, their money reported as
`pipeline_commitment`, and they no longer sort above real owners, because rank in
a cap table reads as ownership. `by_class` follows the same denominator or the
two halves of one table contradict. The decision rides on each row as
`counts_toward_ownership` rather than being re-derived by each of seven consumers.
`exited` is evidence the workflow was used, but is not current ownership.

Mutation-checked, and one mutation earned its keep: removing the filter restores
30%/50%; dropping the `workflow_in_use` guard reproduces the recorded failure
(`test_distwaterfall` -> 0.0); and making `distwaterfall` ignore the flag was
initially NOT caught, because `test_distwaterfall`'s fixture has no prospect. That
gap is now covered through the real API, and the mutation fails with the
$1.8M-to-the-prospect split above.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* SCALE-SEAM (101) — design-phase predicted performance, client.ts 642 -> 603

Six methods out. Five to a new `apps/web/src/api/designPerformance.ts` (energy,
energyModel, energyExportUrl, carbonComplianceReport, projectCarbon) and
benchmarkCosts to cost.ts.

**The seam was drawn by earlier slices, not this one.** operations.ts's own
header records why projectCarbon did not go there — "EMBODIED carbon ... a
design-phase estimate. The GHG figures in esgSummary come from metered utility
data. Same molecule, opposite ends of the asset life" — models.ts records the
parallel call for /energy, and operations.ts does hold /energy/actual. Prediction
versus measurement, committed to twice independently. These five are the
prediction side of an axis this codebase already chose.

Not named environmental.ts on purpose: that names the TOPIC both halves share,
which is exactly what would re-blur the seam operations.ts drew. What separates
them is not subject matter but whether the number is forecast or observed.

**A planned benchmarks.ts was abandoned before any code was written.** Grepping
every /benchmarks caller showed two already live elsewhere: cost.ts holds
unitRates (/benchmarks/unit-rates) and schedule.ts holds benchmarksPullPlanning
(/benchmarks/pull-planning). So the repo had already decided that prefix
distributes by what each method ANSWERS, and a benchmarks.ts would have been
route-prefix grouping contradicting two live placements. benchmarkCosts went to
cost.ts instead, beside unitRates — the same question at a different granularity,
same low/p25/median/p75/high shape. benchmarkResponseRates and
spaceUtilBenchmarks STAYED: no existing mixin owns their question, and inventing
a home for two methods on a guess is what produced this file's UNFILED banner.

Two gates earned their keep. DOC-STRAND caught the extraction stranding
unitRates' doc comment above the inserted block — reunited, not deleted. And the
size ratchet reported 603 where `wc -l` said 602, which is the off-by-one its own
message warns about; the pin took the gate's number.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Portfolio risk heat map — R22-PIPELINE

`GET /portfolio/risk` (`risk_portfolio.py`) grids `risk_board` across the book:
projects down, the five risk engines across (Monte-Carlo schedule risk ·
predictive alerts · EVM · pre-flight gate · overdue coordination), intensity
`3·high + 2·medium + 1·low`. Rendered on Portfolio beside the executive roll-up.

`/portfolio/executive` and `/portfolio/construction` roll up *performance*;
neither could say which risk ENGINE is hot on which project. Cells come from
`risk_board.board` unchanged — same engines, same Monte-Carlo seed — so a cell
and the project's own risk panel cannot disagree. That costs a full board per
project, so the sweep is bounded by `limit` (default 25, clamped 1–100) and
reports `truncated`; the scanned set is a deterministic prefix by name, not the
riskiest projects, because ranking is what the sweep produces and so cannot
choose what to sweep.

AN EMPTY CELL IS NOT A SAFE CELL. A grid of counts renders 0 for two different
facts: this engine looked and found nothing, and this engine could not run.
`board` is fail-open per lane and already separates them, so every cell carries
a `state`; an unmeasured cell carries NO COUNTS AT ALL rather than zeros, and
the UI draws it as a dash. `coverage` reports the split. A clear signal nobody
has a basis for is worse than no heat map — the same lesson as the cap table's
stamped default state, in a second place.

`risk_board.LANES` is new and gated against a REAL board run. `board` reports
coverage under lane keys (`schedule_risk`) while its items carry source strings
(`schedule-risk`); nothing connected the two, and a roll-up must join on both.
`test_risk_portfolio.py` asserts every lane key `board` emits appears in the
table and every `source` its items carry is a value — so a lane added to `board`
alone fails rather than rendering as a column that never lights up.

Both claims mutation-checked: emitting zeros for an error cell, and dropping a
lane from `LANES`, each fail naming the shape. 664/664 backend suites,
2062 web tests, typecheck + lint + build clean.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Review round on #439 — deterministic tie-break, keyboard-operable rows

Two findings from review, both verified real before fixing.

1. STABLE TIE-BREAKER — a bug against this route's own stated contract.
`Project.name` is not unique, and `risk_portfolio`'s docstring promises a
DETERMINISTIC prefix when the sweep truncates. Ordering by name alone leaves
tied rows in whatever order the engine returns, so a tie straddling the `limit`
boundary scans a different project run to run. Now `order_by(Project.name,
Project.id)` — the primary key settles every tie.

Pinned by a test rather than taken on trust: 8 same-named projects at `limit=6`,
asserting the scan takes the four LOWEST-ID rows and not the four first
INSERTED. Mutation-checked — reverting the fix fails it with both id lists
printed. Ids are uuid4 and nothing here can pin one, so a regression escapes
with probability 1/C(8,4) = 1.4%; that number is stated in the test rather than
left implied.

2. KEYBOARD-OPERABLE HEAT-MAP ROWS. `tr.onclick` alone gives keyboard users no
way to open a project. Checking before fixing changed the fix twice:
`.kpi-click:focus-visible` already carries a focus outline in `style.css`, so
the stylesheet was written expecting these rows to be focusable and a
pointer-only handler quietly never delivered it; and `documents.ts` already has
the house idiom — `role="button"`, `tabIndex`, Enter AND Space with
`preventDefault`. Matched that rather than inventing a pattern, plus an
`aria-label` carrying the row's risk count.

Only the row this change added is fixed. The four sibling tables in the same
panel have the identical gap, but they are pre-existing code this change does
not touch; widening into them is the author's call.

Docstrings added to `_score` and `_empty_counts` — the two helpers carrying
ideas worth stating (the intensity weighting, and where a MEASURED zero is
constructed) — and to the two test stand-ins. Matches how `resource_loading.py`
treats its helpers: bare when trivial, documented when the contract is not
obvious.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Cross-project Gantt — R22-PIPELINE

The Programme card now draws a bar per project on a shared span: start, finish,
duration, which project drives the programme finish, and which are named by an
external link.

IT NEEDED NO NEW ENGINE, AND THAT IS THE FINDING. The roadmap recorded a
cross-project Gantt as missing because `schedule_viz.py` is per-project. True,
and not the whole picture: R46's `schedule_portfolio.py` already computes
`project_starts` and `project_finishes` in its one merged pass, and the route
already returned them. `apps/web/src/api/schedule.ts` declared only
`programme_finish`, `project_count` and `external_link_count` — so the dates
reached the browser and were dropped AT THE TYPE BOUNDARY before anything could
draw them. Same class as R37-TESTED-UNWIRED, one layer further out: not a route
without a caller, but a payload without a reader.

Cost of the premise-check: one grep. Cost of believing the entry: a scheduling
engine.

`programmeGantt.ts` holds the geometry as a pure function (7 unit cases); the
panel only paints what it returns.

BARS COME FROM THE MERGED PASS, never each project's standalone CPM — a project
can look comfortable alone and be critical to the programme, and its own run
would show the comfortable answer. Asserted rather than documented:
`test_programme_gantt.py` pins that the FS link pushes fit-out past enabling's
finish, and removing the link fails it with that sentence.

A PROJECT WITH ONLY ONE DATED END GETS NO BAR, and is listed with the reason.
Substituting the programme's own start or finish for the missing end draws a bar
that looks measured and is not — the risk heat map's rule arriving independently
in a second place.

Writing the test also found that an external link names activities by RECORD id:
`wbs` and `ref` are aliases resolved only for a project's own predecessor tokens,
so a link written in WBS terms is refused as "no such activity". Recorded next to
the link that uses it.

2069 web tests (205 files), typecheck + lint + build clean, structural gates
green. Backend suite running.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Review round on #440 — reject normalised dates, require the id separator,
and correct my own wording

Three findings, all verified against the code before fixing.

1. `Date` NORMALISES AN OUT-OF-RANGE DAY instead of rejecting it: "2026-02-30"
parses happily and becomes 2026-03-02, so a bad date drew a bar. Only the month
is range-checked ("2026-13-01" is NaN). `day()` now round-trips through
`toISOString()`. This one bites harder than a generic date nit, because a
normalised date IS an invented one and this module's whole rule is that it does
not draw a bar it cannot measure — the defect was in the guard, not around it.

2. PREFIX COLLISION ON PROJECT IDS. `"p10::A1".startsWith("p1")` is true, so an
external link on p10 flagged p1 as linked and left p10 plain. The separator is
now required. Verified in node rather than reasoned about.

3. MY OWN WORDING WAS FALSE. The roadmap and CHANGELOG said the dates were
"dropped at the type boundary". `HttpCore.json<T>` returns `res.json()` under an
unchecked cast — nothing filters anything at runtime. The dates were in the
parsed response all along; nothing DECLARED them, so no call site could reach
them and none did. Corrected in three places, with the correction recorded in
the roadmap rather than quietly swapped: a plausible-sounding mechanism is
exactly the kind of wrong this file exists to resist.

Both code fixes mutation-checked — reverting each fails its own new test and
nothing else. 10 geometry cases (was 7), 2072 web tests (205 files), tsc and
eslint exit 0, doc gates green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Portfolio resourcing — R22-PIPELINE's last item

`GET /portfolio/resourcing` (`resource_portfolio.py`) sums weekly CONCURRENT
resource demand per trade across projects. `?cap=` flags weeks where one trade
is over-committed across the book and names the competing projects. Rendered on
Portfolio, with the trades on more than one project marked — the only ones that
can be double-booked.

A TRADE ON THREE JOBS IN THE SAME WEEK LOOKS COMFORTABLE ON EVERY ONE OF THEM.
That is what a per-project histogram cannot show and the whole reason for the
endpoint. Proved rather than asserted: two projects at 6 units each are each
under a cap of 8 — verified by calling their own `/schedule/resource-loading?cap=8`
and getting nothing back — while the book reports 12 over the same cap.
Mutation-checked by replacing the cross-project sum with a max, which fails on
the 12-vs-6 assertion.

"BY DEPARTMENT" WAS THE WRONG SHAPE, AND THE SCHEMA SAYS SO.
`resource_assignment.trade` is labelled "Trade / discipline", and "department"
appears nowhere in the backend except a comment in `rooms.py` and a
fire-department scope clause. A department axis is a PRODUCT DECISION — what is
a department that a trade is not? — not a filter over data we hold. Raised in
the roadmap rather than invented: a dimension nobody has defined cannot be
reported honestly. The portfolio axis was the half that mattered, and it needed
no new field.

FIDELITY IS REPORTED, NOT BLENDED. A project with no assignments falls back to
activity `crew_size`, which is a crew count and not a resourced plan, so every
row carries its `source` and `fidelity` gives the split. The heat map's rule one
step along: do not let a lower-fidelity value wear the costume of a
higher-fidelity one.

The two `over_allocation` shapes are NOT interchangeable and both docstrings say
so: this one caps per trade across the book, `resource_loading`'s caps one
project's total weekly units. The test says it too — its fixture puts the
single-project trade on its own project for exactly that reason.

A GATE CAUGHT SOMETHING ON THE WAY IN, AND IT WAS A WORD. The field
`fidelity.resourced` put the substring `sourced` into the web source, and that
is the leaf of `/schedule/eot/sourced`, so `test_route_reachability` reported a
frozen-uncalled route as called. `strip_comments` was no help — the collision
was in an identifier, not prose. Renamed to `assigned`, which names its source
rather than restating an adjective. Second instance of a class that gate already
records; the note there now explains why the matcher is not the thing to change.

2072 web tests, tsc + eslint + build clean, 12 structural gates green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Roadmap truth pass + R39-DECOMP-VIEWER (17)

TWO STALE CLAIMS CORRECTED, both found by testing the entry against the tree.

R38-SYNC-2D3D's stated defect is fixed end to end. The entry said the pipeline
"discards element identity at bake time" and that "nothing in a plan can name
what it draws". `_bake_uncached` returns (guid, ifc_class, mesh) and its own
docstring credits R38-PLAN-IDENTITY; `cut_baked_guided` emits (guid, class,
polyline) with a PRODUCTION caller in the plan renderer; the SVG carries
data-guid and planPane.ts selects on it. The entry described two functions
accurately and drew the wrong conclusion because it never looked for a third.
What actually remains: it claims three open children and names none.

CLAUDE.md's viewer numbers were both stale — "twenty-eight commits" and "3,444
lines" are now 67 and 2,570. Unlike the Node and Python drifts that file already
records, this one moved in the direction that STRENGTHENS its argument, which is
the hardest kind to notice: a number that decays toward the conclusion it
supports never looks wrong.

R39-DECOMP-VIEWER (17) — field verification out of app.ts (2,571 -> 2,508).

app.ts is not a class, so REL-4's "grep the this. refs first" rule has no this.
to grep: the file is ONE 2,445-line function and everything in it is a closure.
The equivalent is how many SIBLING closures a candidate captures, and over all
fourteen candidates >=25 lines exactly ONE captured zero. buildToolsPanel
captures 14, handleKey 12, selectByGuids 6 — every other move would have been the
callback bag REL-4 warns about. Four of five free variables already travelled on
the typed ViewerCtx, so the deps object is that context narrowed.

THE NARRATIVE-CHAIN GATE REFUSED THE FIRST RATCHET ENTRY, CORRECTLY. The previous
entry ended at 2,571 and the file measured 2,570 — one line had left with no
slice recording it, the drift the roadmap cell already documents from another
lane. The entry now runs 2,571 -> 2,508 and names the stray rather than starting
at a number nobody can reproduce. Ratchet mutation-checked at 2,507.

2072 web tests, tsc + eslint + build clean, 8 structural gates green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* SCALE-SEAM (102) — counterparty risk, client.ts 603 -> 589

`prequalScores`, `coiExpiry` and `lienExposure` out to
`apps/web/src/api/counterpartyRisk.ts` — which trade partner is a risk on this
job, and why: are they qualified, are they insured, and do we owe them enough to
be liened.

THE WITNESS IS THAT THE SEAM DISAGREES WITH THE ROUTE PREFIX. Two sit under
/prequal/ and one under /payapp/lien-exposure, so a prefix grouping would have
SPLIT the set — while all three return per-counterparty rows carrying a verdict
about that counterparty: risk_band + flags, days-to-expiry, exposure +
vendors_at_risk.

That is the affirmative form of a rule this repo has only recorded negatively:
(85) rejected "they are all multipart uploads", (89) "they are all module
records", annotate.ts "they all call editIfc" after measuring 24 recipes across
nine categories. A shared mechanism is not a question. Here the mechanism argues
AGAINST the grouping and the shape of the returns argues for it, so the evidence
is not something a name could have produced.

benchmarkResponseRates sits immediately above them and STAYED: it returns
RFI/submittal turnaround and names no counterparty at all — it measures how
responsive the process is. Adjacency is not a relationship, which REL-4 recorded
three separate times this cycle.

Found on the way out: an orphaned PrequalScores type import, the same residue
slice (101) left with EnergyResult.

Ratchet 603 -> 589, mutation-checked at 588 (both the growth assertion and the
history-chain assertion fire). 2072 web tests, tsc + eslint clean, doc gates green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Review fixes on #442, and a gate for the number that keeps drifting

Four CodeRabbit findings, all verified against the tree first. The second was
self-referential and is the interesting one.

This PR corrected CLAUDE.md's stale app.ts line count from "3,444" to 2,570 --
and then R39-DECOMP-VIEWER (17), in the same PR, took the file to 2,508. The
paragraph diagnosing numbers that decay toward the conclusion they support
decayed toward its own conclusion before it merged, and a review bot found it
rather than the author.

So test_claude_md_gates.py now checks that number against the ratchet. The
existing gate asks whether a cited FILE exists; this asks whether a cited NUMBER
is still true. It is cheap only because the value is not really CLAUDE.md's to
hold: test_file_sizes.py already pins the same file at an exact size, so the
prose is a COPY of a gated value, and a copy is what drifts. Mutation-checked
both ways -- a wrong figure fails, and a REWORDED SENTENCE fails too rather than
passing on two Nones, which is the vacuous-green failure that file's own header
calls worse than no gate at all.

R38-SYNC-2D3D is CLOSED, with its children named. The entry claimed three of
four children were open and named none of them. Re-derived by grepping the tree
rather than reading the file that was already wrong: R38-SYNC-SELECT,
R38-SYNC-VIEW, R38-PLAN-TRANSFORM and R38-PLAN-IDENTITY, and
docs/roadmap-completed.md carries a check for EACH. The 2026-08-10 un-archive
was mechanically right -- a lane row pointed at nothing -- and then inherited
the restored text's open count as though the restore had verified it. Nothing
had: R38-PLAN-IDENTITY was marked done that same day, in the archive the entry
was being pulled out of. Un-archiving restores an entry's TEXT, not its truth.

NAMING THOSE CHILDREN MADE THEM ITEMS, AND THE GATES SAID SO. Four bold item
codes in roadmap.md put three new orphans in roadmapLanes.test.ts and a stale
open-vs-implemented pair in roadmapStale.test.ts. The fourth escaped only
because its line happened to contain a check mark in prose. All four now carry
an explicit marker -- passing by accident and passing by construction look
identical until something moves.

Also: completed the verbless counterparty-risk changelog entry, and gave the
bare `wc -l` in CLAUDE.md's re-measure command its argument, since an
instruction to verify that hangs on stdin is one nobody runs twice.

Verified: 2072 web tests, tsc + eslint clean, roadmap lane/stale gates green,
citation gate green and mutation-checked twice.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* SCALE-SEAM (103) — acceptance gates, client.ts 589 -> 572

permitReadiness, diligenceReadiness, handoverAcceptance and validate ->
acceptanceGates.ts: "will an outside party accept this project, and what is
blocking it".

NEITHER THE ROUTE NOR THE AUDIENCE PRODUCES THIS GROUPING. The four routes are
/permit/readiness, /diligence/readiness, /handover/acceptance and /validate --
four different prefixes, so a prefix grouping takes one each and the set never
forms; the shared leaf word "readiness" reaches only two of the four. The
deciding parties are an AHJ, an investor, an owner and an IDS checker -- four
different audiences, so grouping by reader fails too.

What forms it is the RETURN SHAPE: each collapses the whole project to a single
accept/refuse verdict (verdict / go / accepted / status:"pass"|"fail") and then
enumerates what withholds it. (102) was carried by a prefix that actively
DISAGREED with the seam; this one by a vocabulary that says nothing at all --
four names sharing no words can still be one question, which is the inverse of
the error (85), (89) and annotate.ts each recorded, where a shared mechanism
looked like a shared question.

THE TWO EXCLUSIONS DID THE WORK. spineTraceability is the closest miss -- same
domain, adjacent in the file, equally project-scoped -- and returns
coverage/gaps/chain with NO verdict field at all: it maps completeness for a
human rather than deciding acceptance. editPrecheck DOES return a verdict, but
judges a PENDING ACTION ("may I run this recipe with these params"), is remedied
by changing the params you are about to submit, and sits beside addCurtainWall
as the precheck for editIfc.

ONE FALSE POSITIVE, RECORDED BECAUSE IT WAS INVISIBLE. A scan for verdict-shaped
returns also flagged collabSnapshot -- but the match came from the doc comment
introducing permitReadiness, the NEXT method. A method-body splitter that runs
to the next header swallows the comment belonging to that header, so the
population silently inherits its neighbour's vocabulary; a count of six looked
entirely checked. Only reading each candidate caught it.

Also files handoverAcceptance, which an earlier slice had parked under an
explicit UNFILED note asking for it to be placed by what it ANSWERS rather than
by what it sits next to. That note is narrowed to two entries, not deleted --
the other two are still genuinely unfiled, and a note that silently loses
entries is how earlier slices lost methods.

THE DOC-STRAND GATE CAUGHT A DEFECT IN THIS SLICE'S OWN NEW FILE: a /** */ doc
comment on the Ctor type sat directly below the module header, which that gate
reads as a stranded comment -- the header carrying the whole witness was one
line from reading as documentation of a type alias. It is a // comment now,
which is why counterpartyRisk.ts has none there either. The fast checks (tsc,
eslint) were clean while this was broken; the suite is where it lived.

Verified: 2072 web tests / 205 files, tsc + eslint clean, whole-tree ruff clean,
ratchet mutation-checked at 571 (both the growth and chain-end assertions fire),
48-entry narrative chain unbroken, test_route_reachability + test_reachable +
test_import_cycles + test_doc_substance + test_claude_md_gates + test_ruff_scope
+ test_declared_imports green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* SCALE-SEAM (104) — coverage maps, client.ts 572 -> 554

spineTraceability + scopeRegister -> coverageMaps.ts: "how completely is this
project's chain of records linked, and exactly what is missing".

THIS IS THE AFFIRMATIVE HALF OF A BOUNDARY (103) DREW BY EXCLUSION.
acceptanceGates.ts took the four methods that collapse the project to one
accept/refuse verdict, and named spineTraceability as the closest miss PRECISELY
because it maps completeness rather than deciding. Both members here report
proportion-complete across several link types (specs_packaged_pct /
packages_costed_pct / sheets_specced_pct / spec_to_budget_pct; pct_quantified /
pct_allocated / pct_scheduled) plus the individual records lacking the link
(specs_without_bid_package / bid_packages_without_cost_code / sheets_without_spec;
gap_items with per-item gaps[] and status complete|gap). Neither carries a
verdict field. Same test as (103), run for inclusion this time.

DERIVING THE POPULATION REQUIRED RESOLVING NAMED RETURN TYPES, AND THAT IS THE
LESSON. A scan of method bodies for coverage vocabulary returned scopeRegister,
citedQuery and progressActuals -- and MISSED spineTraceability, the strongest
member, because its return is the named type SpineTraceability and its body
contains none of those words. That is the exact MIRROR of the mistake (103)
recorded, where a body scan OVER-counted by matching the doc comment of the next
method. A textual scan of a typed language reads neither the comments nor the
types correctly: it finds candidates, it never counts them.

EXCLUSIONS. citedQuery carries coverage / uncited_claims / fully_cited, but its
product is an ANSWER whose sourcing those annotate -- the caller renders a cited
answer, not a worklist. masterBuilderBrief is THE CLOSEST CALL in this slice,
closer than spineTraceability was to the gates, since it has readiness_pct,
ready_steps and gap_steps; it stays because its product is a narrative brief with
a reframe_prompt and a disclaimer, where the percentages head a document rather
than being it -- recorded rather than asserted, since a later reader may decide
otherwise. progressActuals pct_complete is physical progress against a planned
quantity banded ahead/on_track/behind: variance over time, not completeness of
linkage.

A FOLLOW-UP PROPOSED IN (103) IS WITHDRAWN, AND THAT IS A CORRECTION. #443 said
three consecutive slices leaving an orphaned type import was "a pattern that
wants a gate rather than vigilance". It already has one: tsc reports the orphan
as TS6196 and caught every instance -- EnergyResult (101), PrequalScores (102),
DiligenceReadiness (103) and now SpineTraceability (104). None reached a commit.
Proposing a gate for a class the toolchain already gates is how a checklist grows
without getting safer.

Verified: 2072 web tests / 205 files, tsc + eslint clean, whole-tree ruff clean,
ratchet mutation-checked at 553 (3 assertions fire), 49-entry narrative chain
unbroken, and test_claude_md_gates + test_route_reachability + test_reachable +
test_import_cycles + test_doc_substance + test_ruff_scope + test_declared_imports
all green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

---------

Co-authored-by: Claude <noreply@anthropic.com>

* SCALE-SEAM (95) — element state: two read/write pairs, and why the matrix loses

Moves `lodSummary`/`setLod` and `phasing`/`setPhase` out of `client.ts` into
`api/model.ts`. They answer one question — *what state are the model's elements
in, and set it?* — and `client.ts` goes 727 -> 711, 76 methods above the STAYING
banner.

The grouping is derived, not asserted:

- identical return shape `{ total, <x>ed, prop, counts: Record<...> }`;
- both writers are `(pid, guids, <enum>, publish) -> editIfc`;
- both readers are consumed by `viewer/tools/modelStatePanels.ts` (251, 316);
- both writers sit unwired and *adjacent* on `clientCallers.test.ts`'s UNCALLED
  allowlist;
- `model.ts` already owned `/model/lod/census`, `/lod/handover-readiness` and
  `/lod/assessment`, while the base distribution `/projects/{pid}/lod` was left
  behind in `client.ts` — `lodSummary` was a sibling separated from its family.

`authoring_matrix.py` DISAGREES and is recorded as the losing vote rather than
elided. It files `set_lod` under `data` and `set_phase` under `lifecycle`,
because it categorises by the IFC output each recipe writes — an LOD stage tag
against `Massing_Phasing.Status`. Different property sets, same question, which
is (89)'s "storage is a HOW" trap. This is the first slice where the matrix has
been wrong after being right three running.

It also MEETS (94)'s objection rather than overriding it: that slice declined
`setPhase` because taking the writer alone would have stranded `phasing()`, the
reader/writer split (87) had to undo. Both halves move together here.

The four names are added to `surface.test.ts` because its floor is a slack
ratchet (788 actual vs 751 floor) — the count alone would not notice a loss —
and because the UNCALLED allowlist is about call sites, not the surface.

Verified: tsc 0, lint 0, `vitest run src/api` 27 files / 119 tests, build 0,
`test_file_sizes.py` / `test_claude_md_gates.py` / `test_roadmap_status.py` /
ruff all 0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* SCALE-SEAM (96) — the as-built question's aggregate reader, and a witness that actually bounds

Moves `lod500`, `setManufacturerInfo` and `attachOmDocument` out of `client.ts`
into `api/model.ts`, rejoining `verifyAsbuilt` and `recordAsbuiltDimension`
which (94) moved. `client.ts` goes 711 -> 698, 73 methods above the STAYING
banner.

TWO BOUNDING WITNESSES, derived independently, agreeing:

- `openAsBuiltPanel` in `viewer/tools/modelStatePanels.ts` calls exactly five
  API methods — read off that function's brace closure rather than grepped for,
  so it is the closure of a scope and not a sample. Two of the five were
  already in `model.ts`.
- The reader's own response type names its writer set field by field:
  `verified`/`by_method` from `verify_asbuilt`;
  `with_dimensions`/`dimensions_out_of_tolerance` from
  `record_asbuilt_dimension`; `with_manufacturer`/`with_serial` from
  `set_manufacturer_info`; `with_om_docs`/`om_documents` from
  `attach_om_document`. The backend route says it in prose: "Stamp elements
  with the `verify_asbuilt` recipe."

A reader whose response type enumerates its writers is a DERIVED population.
After eight slices of sampling, that is the first grouping witness here that
bounds a set instead of illustrating one.

WHAT CORROBORATES IS NOT WHAT BOUNDS. `test_lod500.py` reaches exactly three
recipes — `attach_om_document`, `set_manufacturer_info`, `verify_asbuilt` — and
OMITS `record_asbuilt_dimension`, which is unambiguously in this family. It
agrees with the answer without being able to establish it. Three slices claimed
"and no others" off a test file and were wrong all three times.

NOT CLAIMED, and said in the header, the pin, the changelog and the roadmap
rather than only in review: `attachDocument` stays in `client.ts`, takes a
`purpose` parameter, and `asbuilt_summary` counts ANY purpose-tagged document
reference — so "every writer of `with_om_docs` moves here" is false. The field
map is of the recipes each field was designed around, not of everything that
can set it.

Two sources disagree and lose for the same reason: `attach_om_document` is a
purpose-tagged wrapper of `detailing.attach_document`, and
`authoring_matrix.py` files it and `set_manufacturer_info` under `data`. The
first is a shared HELPER, the second a STORAGE bucket — the groupings (89) and
(90) each had to reject. The matrix is the losing vote twice running after
being right three times.

Also fixes the extraction helper: it terminated its brace count on the method
signature line, so a signature wrapping across two lines with no opening brace
on the first read as a 3-line method. `attachOmDocument` is 6.

Verified: tsc 0, lint 0, `vitest run src/api` 27 files / 119 tests, build 0,
ruff (the CI command, from `services/api`) 0, and `test_file_sizes.py`,
`test_claude_md_gates.py`, `test_roadmap_status.py`, `test_ruff_scope.py`,
`test_reachable.py` all 0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* SCALE-SEAM (97) — the undo stack, and a destination that looked right and was not

Moves `editHistory`, `editUndo` and `editRedo` out of `client.ts` into
`api/authoring.ts`. `client.ts` goes 698 -> 687, 70 methods above the STAYING
banner.

WHY THAT MIXIN: `editIfc`, already there, is the PUSH they pop. `authoring.py`
records the pre-edit version on every `/edit` call "so this edit can be undone",
`_restore_version` pops that stack, and `edit_history.state()` reads its depths.
One stack, and the operation that fills it was already in this file.

The types agree: both writers return `{restored, state: {can_undo, can_redo}}`,
and `state` is `editHistory`'s own return type minus the depths — the writers
hand back the reader's answer. That is a type-level relation, not the shared
`/edit/` prefix. The prefix is real and is deliberately not the argument, since
a route prefix is exactly what the verification slice was caught grouping on.

A HYPOTHESIS TESTED AND WITHDRAWN, which is the part worth keeping. "Undo
restores the prior model version" makes `model.ts` the obvious home — it owns
`modelVersions`, `versionDiff`, `versionCostDelta`. It is the wrong home: those
read `/projects/{pid}/versions` out of `bim.py`, while undo pops a DIFFERENT
stack, the `edit_history` sidecar, which `recipe_log.py` describes as a list of
file paths with "No recipe, no parameters, no actor". Two stacks, one word — and
the word is what made the wrong answer look obvious. Second withdrawal of a
plausible destination after checking it, after (93) withdrew (92)'s `HttpCore`
forecast.

THE BOUND IS WEAKER THAN (96)'s AND IS STATED THAT WAY. `app.ts`'s S4 block
wires `refreshUndo` (calling only `editHistory`) and `doUndoRedo` (calling only
`editUndo`/`editRedo`), so the union is exactly these three — but that unit is a
block delimited by reading, not a closure the braces define. It corroborates; it
does not bound. Not every set has a witness as strong as the last one's, and
promoting a block to a closure would be this sequence's own recurring defect.

Verified: tsc 0, lint 0, `vitest run src/api` 27 files / 119 tests, build 0,
ruff (the CI command, from `services/api`) 0, and `test_file_sizes.py`,
`test_claude_md_gates.py`, `test_roadmap_status.py` all 0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Correct the undo/redo republish docs — all three sites, not just the flagged one

CodeRabbit flagged `editUndo`'s docstring on #414: it says "restore the prior
model version + republish" unconditionally, but `publish` defaults to true and
can be false. Verified against the backend — `_restore_version` guards the
republish with `if publish:` — so the claim is wrong whenever a caller passes
`publish: false`.

Grepping every site of that wording found the same unconditional claim in THREE
live places, not one:

- `apps/web/src/api/authoring.ts` — `editUndo` (the flagged one)
- `services/api/src/aec_api/routers/authoring.py` — the `/edit/undo` route
- `services/api/src/aec_api/routers/authoring.py` — the `/edit/redo` route

All three now say republishing happens only when `publish`. The remaining hits
are UI button labels, where the call site never passes the flag so republish
really is unconditional, and historical CHANGELOG entries; both are correct as
written and are left alone.

Also fixes the same defect's other half in the same five lines: the declared
return type omitted `publish`, which the backend adds as `"running"` when it
republishes. Correcting the prose while leaving the type silent about the same
conditional would be the half-applied fix this sequence has twice been caught
making.

Verified: tsc 0, lint 0, `vitest run src/api` 27 files / 119 tests, build 0,
ruff (the CI command, from `services/api`) 0, `test_file_sizes.py` 0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* SCALE-SEAM (98) — detailing carriers, and a field map total over one module but not the codebase

Moves `elementDetailing`, `classify`, `applyDetailingRules`, `validateDetailing`
and `attachDocument` out of `client.ts` into a new `api/detailing.ts`.
`client.ts` goes 687 -> 665, 65 methods above the STAYING banner.

WHAT THEY ANSWER: what informational carriers are attached to this element,
write them, and which are missing?

THE WITNESS IS A 1:1 AND TOTAL FIELD-TO-WRITER MAP, the shape (96) established.
`element_detailing` walks `HasAssociations` and branches on exactly two
relationship types, and `detailing.py` holds exactly two writers, one per
response array:

  classifications[]  <-  classify        (IfcRelAssociatesClassification)
  documents[]        <-  attachDocument  (IfcRelAssociatesDocument)

The map is read out of the reader's own body, not matched on names. The other
two methods are those same writes automated and audited: `applyDetailingRules`
runs the condition-to-content rule set and writes both carrier kinds,
`validateDetailing` reports elements a rule applies to that lack the code.

TOTAL OVER THE MODULE, NOT THE CODEBASE, and the difference is the claim.
`attachOmDocument` — moved to `model.ts` in (96) — wraps the SAME
`detailing.attach_document` and also lands in `documents[]`, so "these are all
the writers of this reader's fields" is false. That overlap was recorded when it
moved, which is why it was on hand to qualify this slice rather than being found
in review.

ADJACENCY AGREED WITH THE ANSWER AND IS NOT EVIDENCE FOR IT. These five were
contiguous in `client.ts`; unlike (95), where non-contiguity was the whole
argument, a positional split would have found this set too. Stated precisely
because it looks like support.

ALSO RECORDED: `api.classify()` has no call site — `detailingSection.ts` drives
the recipe through the generic `authorAndReload` path, bypassing the typed
method, and `clientCallers.test.ts` counts it reached because it matches bare
string literals as well as calls. That looseness is deliberate per that file's
own docstring, so it is a limit of the gate rather than a defect in it.

The new mixin needs `editIfc`, so it declares `NeedsEditIfc` and composes
outside `withAuthoring`; `compositionOrder.test.ts` gains a fourth assertion.
MUTATION-CHECKED: relaxing the constraint to `Ctor<any>` produces "TS2578:
Unused '@ts-expect-error' directive" on exactly the new line, so it fails for
the reason claimed rather than merely passing.

The extraction removed 27 lines and the banner plus import added 5 back — caught
by the ratchet, not by me, the same way (94) found its own banner growth.

Verified: tsc 0, lint 0, `vitest run src/api` 27 files / 119 tests, build 0,
ruff (the CI command, from `services/api`) 0, and `test_file_sizes.py`,
`test_claude_md_gates.py`, `test_roadmap_status.py` all 0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* SCALE-SEAM (99) — the content shelf, and a destination header that was wrong until now

Moves `contentCatalog`, `placeContent` and `importContent` out of `client.ts`
into `api/authoring.ts`. `client.ts` goes 665 -> 648, 62 methods above the
STAYING banner.

WHAT THEY ANSWER: what pre-made content can I place, and place it?

THE WITNESS IS A ROLE-FOR-ROLE PARALLEL with the family shelf already in that
file, read off the signatures rather than the shared noun:

  catalog reader    familyCatalog()  {count, categories: Record<..>}
                    contentCatalog() {count, note, groups: Record<..>}
  placer            placeFamily(pid, family, position)
                    placeContent(pid, category, point, name)
  multipart import  async importFamilies(pid, file, ..)
                    async importContent(pid, file, opts)

Three roles, three methods each, matching shapes and arities. A parallel between
two method TRIPLES is structural; "both are shelves" would have been a shared
word, which is the grouping (88) and (89) each had to reject.

THE DESTINATION'S OWN FIRST LINE WAS WRONG UNTIL THIS COMMIT. `authoring.ts` has
described itself as holding "the family/content shelf" while containing ZERO
content methods — the word's only other appearances there are an HTTP header and
a sentence about IFC *type* content. The docstring stated an intended scope as
fact.

That is recorded as corroboration that was FALSE, not as evidence. A header
agreeing with the answer is worth nothing until someone checks whether it is
true, and this one had been wrong for as long as it had existed. It is the
smallest possible instance of the drift the project instructions keep warning
about.

Verified: tsc 0, lint 0, `vitest run src/api` 27 files / 119 tests, build 0,
ruff (the CI command, from `services/api`) 0, and `test_file_sizes.py`,
`test_claude_md_gates.py`, `test_roadmap_status.py` all 0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* SCALE-SEAM (100) — the element-connection pair, and a destination named at its real strength

Moves `elementConnections` and `connectElements` out of `client.ts` into
`api/model.ts`. `client.ts` goes 648 -> 642, 60 methods above the STAYING
banner.

WHAT THEY ANSWER: what is physically joined to what, and record a joint?

THE PAIR IS BOUND BY THE BACKEND NAMING ITS OWN WRITER, the (96) shape: the
`/element-connections` route docstring reads "Author edges with the
`connect_elements` recipe (POST /edit with {guid_a, guid_b})". Reader and
writer, one relationship type (IfcRelConnectsElements), both marked B5.

THE DESTINATION ARGUMENT IS WEAKER THAN THE PAIRING ARGUMENT AND IS LABELLED SO.
`model.ts` owns `modelGraphStats`, whose `by_rel` counts the IFC relationship
graph BY RELATION — IfcRelConnectsElements being one — and `graphNeighbors`,
which walks it. So this pair is one relation of a graph the file already reads,
plus its authoring verb. That is a SPECIALISATION, not an identity: the graph
methods are generic traversal over every IfcRel*, these two are one relation
with a verb attached. The pairing is evidenced; the placement is a judgement,
and collapsing the two into one confident sentence is the overstatement this
sequence keeps catching.

TWO CANDIDATES REJECTED ON CHECKABLE GROUNDS. `connections.ts` is the trap: it
is DATA-SOURCE connections — SQL, ACC, Procore — sharing nothing with this but
the English word, and it is the file a name-based search lands on first. (97)
found two version stacks behind one word; this is the same collision in a
destination rather than a source. `elements.ts` holds element ATTRIBUTES and
views, and a relationship between two elements is not an attribute of either.

`addBasePlate`/`addShearTab` did not come despite sharing `connections.py` with
these: a backend module is a HOW, the grouping (89) had to reject, and those two
author PHYSICAL assemblies rather than relationship edges.

FOUND WHILE DERIVING, RECORDED NOT FIXED: `add_connection_assembly` (B5,
IfcRelConnectsWithRealizingElements) has no client method anywhere in
`apps/web/src` — a backend recipe with no web exposure, the class (93) recorded
for three MEP recipes.

Verified: tsc 0, lint 0, `vitest run src/api` 27 files / 119 tests, build 0,
ruff (the CI command, from `services/api`) 0, and `test_file_sizes.py`,
`test_claude_md_gates.py`, `test_roadmap_status.py` all 0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* R22-ENTITLEMENT ⑤ — an agency review comment becomes an RFI somebody owns

`RecordComment` had NO outward link of any kind. An agency's comment on an
`entitlement` or `permit` was a text blob at the end of a thread: readable, and
impossible to assign, track or close. ④ made comments survive a revision — the
INBOUND half of "round-tripping"; this is the outbound half the ring entry still
listed as remaining.

`POST /projects/{pid}/modules/{key}/{rid}/comments/{cid}/promote` mints a Topic
carrying the comment text, the source record's ref and its `element_guids`, and
writes a back-link on the comment.

THE BACK-LINK IS THE IDEMPOTENCY. A second promote 409s instead of minting a
duplicate RFI — the failure mode a promote button produces on every
double-click. Both load-bearing assertions in `test_comment_promote.py` were
MUTATION-CHECKED: removing the 409 guard makes one comment mint two RFIs (the
failure output shows both `comment.promote` activity entries), and removing the
back-link write drops `topic_id` from the comment.

Follows `promote_markup` rather than inventing a second idiom — mint, carry
provenance, link back, 409, audit.

REACHABLE, NOT MERELY BUILT: the control renders beside the comment and is
replaced by "→ RFI raised" once promoted, because a button whose only remaining
outcome is a 409 is worse than no button.

Adding it turned `register.ts`'s extraction ratchet red, and the remedy is the
one that file states — extraction, never headroom. The comment thread, composer
and new control came out to `portal/register/recordComments.ts` (2,516 -> 2,505,
pin lowered with it). A genuine leaf: it touches the record's comments, the API
and a reload callback and nothing else on the class, and the directory already
holds three leaves extracted the same way.

WHAT THE PREMISE-CHECK FOUND, and it is why this slice exists. The entry's
"Remaining:" line named two things and contradicted itself on one — it listed
submittal packages flatly while the note above it said the inbound half had
shipped. Measured: the inbound view is real, but assembling a package to send is
not, because `modules/transmittal/module.json` types `items` as a textarea and
`to_company` as plain text. Package contents are prose no machine can resolve
back to the records named, and the recipient cannot be the agency an
`entitlement` names, since that is free text too. That is a SCHEMA question, not
a workflow one — which is why reading the workflow surface kept reporting it
done. The roadmap now says that instead of the flat line.

Also corrected: the roadmap's argument against picking SCALE-SEAM quoted
`client.ts` at 2,837 lines. It is 642 — copied forward through every slice since,
the exact drift the rows beside it document twice.

Verified: tsc 0, lint 0, build 0, `vitest run src/portal src/api` 50 files / 275
tests, ruff (the CI command, from `services/api`) 0, and `test_comment_promote`,
`test_modules`, `test_topic_lifecycle`, `test_reachable`, `test_declared_imports`,
`test_ruff_scope`, `test_file_sizes`, `test_claude_md_gates`,
`test_roadmap_status`, `test_doc_substance`, `test_alembic_single_head` all 0.
Full 660-suite running as a cross-check.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* R22-ENTITLEMENT ⑤ review: promotion claims the comment atomically, and a blank one no longer 500s

Two findings on #434, both reproduced before fixing and both mutation-checked after.

**A whitespace-only comment 500s on promote.** The comment route takes
`text: str = Body(...)` with no min-length, so `{"text": "   \n  "}` is a 201.
Promoting it ran `.strip().splitlines()[0]` over an empty list — IndexError.
The `or f"{key} {ref} review comment"` fallback written for exactly this case
had never been reachable at all: when the list is non-empty its first element
is never blank, so the `or` arm could not fire. The guard makes it live.

**Promotion idempotency was not atomic — and the damage is worse than a
duplicate.** `SessionLocal` is `expire_on_commit=False`, so a request that read
the comment before a concurrent promote committed keeps seeing a null back-link
for as long as it holds the session; the `if cm.topic_id` guard reads that stale
copy. A plain assignment then let the later writer overwrite the back-link,
minting a second RFI AND orphaning the first, whose Topic no comment pointed at
any more. The claim is now a conditional `UPDATE ... WHERE topic_id IS NULL`:
under Postgres read-committed the loser blocks on the winner's row lock and
re-evaluates the predicate against the committed row; under SQLite the writes
serialize to the same effect. Rolling back discards the Topic flushed a moment
earlier, so a losing promote leaves nothing behind.

The race test is deterministic rather than timing-dependent — the loser reads,
the winner commits, the loser proceeds from its stale identity map, which is the
production sequence. Mutation-checked both ways: restoring the unguarded index
raises IndexError, restoring the plain assignment fails "a stale-read promote
must be refused, not duplicated".

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* R24-REPORTS-BY-MOMENT — a finished pack can be sent, not only downloaded

`POST /projects/{pid}/jobs/{job_id}/deliver` emails any finished job's artifact
to named recipients, surfaced as **Send** beside **Download** in the job tray.

**The roadmap named the wrong blocker, one layer too high.** The entry said
making a pack a scheduled deliverable "still wants a delivery surface and SMTP".
Both already existed when that was written: `mailer.py` sends real mail (stdlib
smtplib, a Settings "Test connection" button), and `POST …/notifications/digest`
is a working assemble-then-send surface returning a per-recipient status map.
What was actually missing was one size smaller — **the mailer could not carry a
file**. That is why the entry sat: the two things it named were present, so every
look confirmed it and nobody checked the layer below.

`build_message` gained attachments. The ORDER is load-bearing: `add_alternative`
must run before `add_attachment`, or the html body lands inside the mixed part —
Python's EmailMessage refuses outright ("Cannot convert mixed to alternative"),
which the test asserts rather than assumes.

Refusals mirror the download route exactly (404 wrong project, 409 while
queued/running, 404 with no artifact) so a caller does not learn two answers to
"is this artifact ready", plus two of delivery's own: an empty recipient list is
422 rather than a silent success, and over 15 MB is 413 rather than a
per-recipient error from a server that would have bounced it anyway. An
unconfigured deployment returns 200 with every recipient `disabled`, so the UI
reads `smtp_configured` before claiming a send. The delivery is audited — a file
leaving the system is what an audit log is for.

**Not shipped, deliberately: the SCHEDULED half.** There is no scheduler of any
kind in this tree — no APScheduler, no croniter, no cron — so the existing digest
is admin-triggered and nothing runs on a date. Choosing in-process versus
external cron hitting an endpoint is a deployment decision with different
operational consequences, not a wiring task. The roadmap now says that instead of
naming two things that already ship.

Mutation-checked, four ways on the route and one on the tray: dropping the
empty-recipient refusal reproduces the silent success it exists to prevent (200
with `"results":{}`); dropping the size cap admits 15 MB + 1; ignoring
attachments loses the file; attaching before the alternative raises; and ungating
Send from `hasArtifact` offers it on a job with nothing to send.

The client-caller gate did its job here — it failed the build because
`deliverJobArtifact` had no screen, which is what drove the job-tray wiring
rather than shipping another endpoint nobody can reach.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Review round on #435: five findings, all verified real, all fixed

**1. A malformed recipient aborted the whole delivery (Major).** `send_email`
built the message BEFORE its try block. `EmailMessage` rejects a header value
containing CR/LF with ValueError, and this function is documented to never raise
— so one bad address raised out of the loop after earlier recipients had already
received the artifact and before the audit row was written, leaving the record
disagreeing with what happened. Construction moved inside the protected flow;
a bad address is now that recipient's "error" and nobody else's. Also built (and
discarded) on the unconfigured path, so a malformed address does not become
visible only in production.

**2. STARTTLS presented an unverified context (Major, CWE-295).** The finding's
stated reason was wrong — it said "Python 3.9 uses an unverified context" and
this repo is on 3.12 — but the conclusion holds on 3.12 too: measured,
`ssl._create_stdlib_context()` reports verify_mode=0 and check_hostname=False,
so the artifact and the SMTP password went up with no certificate check. Both
call sites now pass `ssl.create_default_context()`.

**3. The size cap ran AFTER materialising the object (Major).** `storage.get`
pulls the whole artifact into memory and `len(data)` checked it afterwards, so
the memory was already spent on exactly the payload being refused — and
concurrent callers multiply it. `storage.size(key)` already existed; the check
now runs before the read.

**4. Recipients were unbounded and undeduplicated (Major, CWE-770).** Each
address is a synchronous SMTP conversation with a 15-second timeout, so an
unbounded list occupies a worker for hours. Now de-duplicated case-insensitively
(preserving caller order) and capped at 25 — as a 422 refusal, not a silent trim,
because quietly dropping recipients is the same silent-success failure the
empty-list 422 exists to prevent.

**5. The test stole the runner's STORAGE_DIR (Minor).** `run_tests.py` assigns
`STORAGE_DIR=./_storage_{test}` and sweeps exactly that path; the test overwrote
it, so its 15 MiB blob landed somewhere the runner does not own. That is what the
suite footer's "dir(s) this runner does not own" counts, and the stray directory
was sitting on disk at 61 MB. Now `setdefault`.

Every fix is mutation-checked. Restoring the pre-fix code fails with: build
outside the try -> AssertionError on the per-recipient result map; size-after-read
-> "materialised <key>" from a patched storage.get, which proves the object was
pulled in; no cap -> 26 recipients accepted; no dedup -> a@ and A@ both served;
bare starttls() -> "called with no context — that context does NOT verify",
asserted through a fake SMTP that captures what is actually passed rather than by
reading the source.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Second review round on #435: the port fix is the root cause my first fix missed

Three new findings on the fix commit. Two were real defects, one is a design
question answered rather than obeyed.

**A mistyped SMTP port escaped the no-raise boundary (Major) — and this is the
SAME defect class the previous commit fixed, one line above the guard.** That fix
moved `build_message` inside the try and left `int(AEC_SMTP_PORT)` outside it.
Settings are stored as arbitrary strings (`settings_store.set_value(db, k,
str(v))`, no numeric validation), so a typo in the Settings form raised
ValueError straight through a function documented never to raise, aborting the
delivery loop before its audit row — exactly the failure the CR/LF fix was for.
Treating the instance instead of the class is what left it. The whole prologue is
now inside the boundary: this function returns a status for ANY input,
configuration included.

**A recipient could forge log lines (Minor, CWE-117).** Both exception handlers
logged `to` with `%s`, so CR/LF in an address writes literal newlines into the
stream and a recipient can append a plausible-looking record of its own. Now
`%r`, which escapes them — the value is still reported, never as its own line.
This one was introduced by my previous commit, not found in old code.

**Cleartext SMTP auth: warned, not refused — deliberately.** The finding asks to
reject `send_email`/`smtp_test` outright when `AEC_SMTP_TLS=0`. That is a
documented deployment choice for a self-hosted product relaying through localhost
or a trusted internal MTA, where cleartext is not an exposure; hard-refusing
would break those installs to protect against a risk they do not have. What is
not defensible is doing it silently, so a credential sent without TLS now logs a
warning naming the setting and the remedy. The password is never logged, and the
test asserts that.

Mutation-checked: %s in place of %r puts the forged line back in the stream;
moving the port parse back outside the try loses the "error" status; removing the
warning loses the cleartext notice. The password assertion was rewritten after it
passed for the wrong reason — the fixture used "p" as the password and the
haystack was full of the letter p, so it now uses a distinctive value.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Only committed capital owns anything — cap table and waterfall

`capital.cap_table` summed `commitment` across every investor whatever their
workflow state. A `prospect` carrying a $10M interest and $0 contributed took
50% of a $10M cap table and halved a real LP from 60% to 30%. It did not stop at
display: `distwaterfall` allocates `share = lp_total * (commitment / lp_commit)`
off these rows, so the prospect drew **$1,818,181.82 of a $2M distribution**
while the committed LP got $181,818.18.

**The obvious filter is wrong on its own, which is why this took a guard.**
`investor` declares `initial: prospect` and every record is stamped with it at
creation, so on a project where nobody ran the `commit` transition EVERY investor
is a prospect and filtering empties the cap table. The roadmap records this was
implemented once and made `test_distwaterfall` return 0.0 instead of $2,000,000.

`workflow_in_use` separates two readings of the same value: **a default state is
not a signal.** Until some investor has moved off the stamped initial state,
`prospect` means "nobody used the workflow" and everyone counts, exactly as
before. Once one has, `prospect` means "not committed" and the state is evidence.

Of the three options the roadmap put to the owner, this is (c). (b) — keying on
`contributed > 0` — was rejected as a domain error: in an uncalled fund an LP
with a signed commitment and no contribution yet is normal, and that rule would
zero out real LPs who simply have not been called. (a) — changing the initial
state — needs a data migration and rewires the default entry path.

Prospect rows are never dropped: they stay visible at 0%, their money reported as
`pipeline_commitment`, and they no longer sort above real owners, because rank in
a cap table reads as ownership. `by_class` follows the same denominator or the
two halves of one table contradict. The decision rides on each row as
`counts_toward_ownership` rather than being re-derived by each of seven consumers.
`exited` is evidence the workflow was used, but is not current ownership.

Mutation-checked, and one mutation earned its keep: removing the filter restores
30%/50%; dropping the `workflow_in_use` guard reproduces the recorded failure
(`test_distwaterfall` -> 0.0); and making `distwaterfall` ignore the flag was
initially NOT caught, because `test_distwaterfall`'s fixture has no prospect. That
gap is now covered through the real API, and the mutation fails with the
$1.8M-to-the-prospect split above.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* SCALE-SEAM (101) — design-phase predicted performance, client.ts 642 -> 603

Six methods out. Five to a new `apps/web/src/api/designPerformance.ts` (energy,
energyModel, energyExportUrl, carbonComplianceReport, projectCarbon) and
benchmarkCosts to cost.ts.

**The seam was drawn by earlier slices, not this one.** operations.ts's own
header records why projectCarbon did not go there — "EMBODIED carbon ... a
design-phase estimate. The GHG figures in esgSummary come from metered utility
data. Same molecule, opposite ends of the asset life" — models.ts records the
parallel call for /energy, and operations.ts does hold /energy/actual. Prediction
versus measurement, committed to twice independently. These five are the
prediction side of an axis this codebase already chose.

Not named environmental.ts on purpose: that names the TOPIC both halves share,
which is exactly what would re-blur the seam operations.ts drew. What separates
them is not subject matter but whether the number is forecast or observed.

**A planned benchmarks.ts was abandoned before any code was written.** Grepping
every /benchmarks caller showed two already live elsewhere: cost.ts holds
unitRates (/benchmarks/unit-rates) and schedule.ts holds benchmarksPullPlanning
(/benchmarks/pull-planning). So the repo had already decided that prefix
distributes by what each method ANSWERS, and a benchmarks.ts would have been
route-prefix grouping contradicting two live placements. benchmarkCosts went to
cost.ts instead, beside unitRates — the same question at a different granularity,
same low/p25/median/p75/high shape. benchmarkResponseRates and
spaceUtilBenchmarks STAYED: no existing mixin owns their question, and inventing
a home for two methods on a guess is what produced this file's UNFILED banner.

Two gates earned their keep. DOC-STRAND caught the extraction stranding
unitRates' doc comment above the inserted block — reunited, not deleted. And the
size ratchet reported 603 where `wc -l` said 602, which is the off-by-one its own
message warns about; the pin took the gate's number.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Portfolio risk heat map — R22-PIPELINE

`GET /portfolio/risk` (`risk_portfolio.py`) grids `risk_board` across the book:
projects down, the five risk engines across (Monte-Carlo schedule risk ·
predictive alerts · EVM · pre-flight gate · overdue coordination), intensity
`3·high + 2·medium + 1·low`. Rendered on Portfolio beside the executive roll-up.

`/portfolio/executive` and `/portfolio/construction` roll up *performance*;
neither could say which risk ENGINE is hot on which project. Cells come from
`risk_board.board` unchanged — same engines, same Monte-Carlo seed — so a cell
and the project's own risk panel cannot disagree. That costs a full board per
project, so the sweep is bounded by `limit` (default 25, clamped 1–100) and
reports `truncated`; the scanned set is a deterministic prefix by name, not the
riskiest projects, because ranking is what the sweep produces and so cannot
choose what to sweep.

AN EMPTY CELL IS NOT A SAFE CELL. A grid of counts renders 0 for two different
facts: this engine looked and found nothing, and this engine could not run.
`board` is fail-open per lane and already separates them, so every cell carries
a `state`; an unmeasured cell carries NO COUNTS AT ALL rather than zeros, and
the UI draws it as a dash. `coverage` reports the split. A clear signal nobody
has a basis for is worse than no heat map — the same lesson as the cap table's
stamped default state, in a second place.

`risk_board.LANES` is new and gated against a REAL board run. `board` reports
coverage under lane keys (`schedule_risk`) while its items carry source strings
(`schedule-risk`); nothing connected the two, and a roll-up must join on both.
`test_risk_portfolio.py` asserts every lane key `board` emits appears in the
table and every `source` its items carry is a value — so a lane added to `board`
alone fails rather than rendering as a column that never lights up.

Both claims mutation-checked: emitting zeros for an error cell, and dropping a
lane from `LANES`, each fail naming the shape. 664/664 backend suites,
2062 web tests, typecheck + lint + build clean.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Review round on #439 — deterministic tie-break, keyboard-operable rows

Two findings from review, both verified real before fixing.

1. STABLE TIE-BREAKER — a bug against this route's own stated contract.
`Project.name` is not unique, and `risk_portfolio`'s docstring promises a
DETERMINISTIC prefix when the sweep truncates. Ordering by name alone leaves
tied rows in whatever order the engine returns, so a tie straddling the `limit`
boundary scans a different project run to run. Now `order_by(Project.name,
Project.id)` — the primary key settles every tie.

Pinned by a test rather than taken on trust: 8 same-named projects at `limit=6`,
asserting the scan takes the four LOWEST-ID rows and not the four first
INSERTED. Mutation-checked — reverting the fix fails it with both id lists
printed. Ids are uuid4 and nothing here can pin one, so a regression escapes
with probability 1/C(8,4) = 1.4%; that number is stated in the test rather than
left implied.

2. KEYBOARD-OPERABLE HEAT-MAP ROWS. `tr.onclick` alone gives keyboard users no
way to open a project. Checking before fixing changed the fix twice:
`.kpi-click:focus-visible` already carries a focus outline in `style.css`, so
the stylesheet was written expecting these rows to be focusable and a
pointer-only handler quietly never delivered it; and `documents.ts` already has
the house idiom — `role="button"`, `tabIndex`, Enter AND Space with
`preventDefault`. Matched that rather than inventing a pattern, plus an
`aria-label` carrying the row's risk count.

Only the row this change added is fixed. The four sibling tables in the same
panel have the identical gap, but they are pre-existing code this change does
not touch; widening into them is the author's call.

Docstrings added to `_score` and `_empty_counts` — the two helpers carrying
ideas worth stating (the intensity weighting, and where a MEASURED zero is
constructed) — and to the two test stand-ins. Matches how `resource_loading.py`
treats its helpers: bare when trivial, documented when the contract is not
obvious.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Cross-project Gantt — R22-PIPELINE

The Programme card now draws a bar per project on a shared span: start, finish,
duration, which project drives the programme finish, and which are named by an
external link.

IT NEEDED NO NEW ENGINE, AND THAT IS THE FINDING. The roadmap recorded a
cross-project Gantt as missing because `schedule_viz.py` is per-project. True,
and not the whole picture: R46's `schedule_portfolio.py` already computes
`project_starts` and `project_finishes` in its one merged pass, and the route
already returned them. `apps/web/src/api/schedule.ts` declared only
`programme_finish`, `project_count` and `external_link_count` — so the dates
reached the browser and were dropped AT THE TYPE BOUNDARY before anything could
draw them. Same class as R37-TESTED-UNWIRED, one layer further out: not a route
without a caller, but a payload without a reader.

Cost of the premise-check: one grep. Cost of believing the entry: a scheduling
engine.

`programmeGantt.ts` holds the geometry as a pure function (7 unit cases); the
panel only paints what it returns.

BARS COME FROM THE MERGED PASS, never each project's standalone CPM — a project
can look comfortable alone and be critical to the programme, and its own run
would show the comfortable answer. Asserted rather than documented:
`test_programme_gantt.py` pins that the FS link pushes fit-out past enabling's
finish, and removing the link fails it with that sentence.

A PROJECT WITH ONLY ONE DATED END GETS NO BAR, and is listed with the reason.
Substituting the programme's own start or finish for the missing end draws a bar
that looks measured and is not — the risk heat map's rule arriving independently
in a second place.

Writing the test also found that an external link names activities by RECORD id:
`wbs` and `ref` are aliases resolved only for a project's own predecessor tokens,
so a link written in WBS terms is refused as "no such activity". Recorded next to
the link that uses it.

2069 web tests (205 files), typecheck + lint + build clean, structural gates
green. Backend suite running.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Review round on #440 — reject normalised dates, require the id separator,
and correct my own wording

Three findings, all verified against the code before fixing.

1. `Date` NORMALISES AN OUT-OF-RANGE DAY instead of rejecting it: "2026-02-30"
parses happily and becomes 2026-03-02, so a bad date drew a bar. Only the month
is range-checked ("2026-13-01" is NaN). `day()` now round-trips through
`toISOString()`. This one bites harder than a generic date nit, because a
normalised date IS an invented one and this module's whole rule is that it does
not draw a bar it cannot measure — the defect was in the guard, not around it.

2. PREFIX COLLISION ON PROJECT IDS. `"p10::A1".startsWith("p1")` is true, so an
external link on p10 flagged p1 as linked and left p10 plain. The separator is
now required. Verified in node rather than reasoned about.

3. MY OWN WORDING WAS FALSE. The roadmap and CHANGELOG said the dates were
"dropped at the type boundary". `HttpCore.json<T>` returns `res.json()` under an
unchecked cast — nothing filters anything at runtime. The dates were in the
parsed response all along; nothing DECLARED them, so no call site could reach
them and none did. Corrected in three places, with the correction recorded in
the roadmap rather than quietly swapped: a plausible-sounding mechanism is
exactly the kind of wrong this file exists to resist.

Both code fixes mutation-checked — reverting each fails its own new test and
nothing else. 10 geometry cases (was 7), 2072 web tests (205 files), tsc and
eslint exit 0, doc gates green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Portfolio resourcing — R22-PIPELINE's last item

`GET /portfolio/resourcing` (`resource_portfolio.py`) sums weekly CONCURRENT
resource demand per trade across projects. `?cap=` flags weeks where one trade
is over-committed across the book and names the competing projects. Rendered on
Portfolio, with the trades on more than one project marked — the only ones that
can be double-booked.

A TRADE ON THREE JOBS IN THE SAME WEEK LOOKS COMFORTABLE ON EVERY ONE OF THEM.
That is what a per-project histogram cannot show and the whole reason for the
endpoint. Proved rather than asserted: two projects at 6 units each are each
under a cap of 8 — verified by calling their own `/schedule/resource-loading?cap=8`
and getting nothing back — while the book reports 12 over the same cap.
Mutation-checked by replacing the cross-project sum with a max, which fails on
the 12-vs-6 assertion.

"BY DEPARTMENT" WAS THE WRONG SHAPE, AND THE SCHEMA SAYS SO.
`resource_assignment.trade` is labelled "Trade / discipline", and "department"
appears nowhere in the backend except a comment in `rooms.py` and a
fire-department scope clause. A department axis is a PRODUCT DECISION — what is
a department that a trade is not? — not a filter over data we hold. Raised in
the roadmap rather than invented: a dimension nobody has defined cannot be
reported honestly. The portfolio axis was the half that mattered, and it needed
no new field.

FIDELITY IS REPORTED, NOT BLENDED. A project with no assignments falls back to
activity `crew_size`, which is a crew count and not a resourced plan, so every
row carries its `source` and `fidelity` gives the split. The heat map's rule one
step along: do not let a lower-fidelity value wear the costume of a
higher-fidelity one.

The two `over_allocation` shapes are NOT interchangeable and both docstrings say
so: this one caps per trade across the book, `resource_loading`'s caps one
project's total weekly units. The test says it too — its fixture puts the
single-project trade on its own project for exactly that reason.

A GATE CAUGHT SOMETHING ON THE WAY IN, AND IT WAS A WORD. The field
`fidelity.resourced` put the substring `sourced` into the web source, and that
is the leaf of `/schedule/eot/sourced`, so `test_route_reachability` reported a
frozen-uncalled route as called. `strip_comments` was no help — the collision
was in an identifier, not prose. Renamed to `assigned`, which names its source
rather than restating an adjective. Second instance of a class that gate already
records; the note there now explains why the matcher is not the thing to change.

2072 web tests, tsc + eslint + build clean, 12 structural gates green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Roadmap truth pass + R39-DECOMP-VIEWER (17)

TWO STALE CLAIMS CORRECTED, both found by testing the entry against the tree.

R38-SYNC-2D3D's stated defect is fixed end to end. The entry said the pipeline
"discards element identity at bake time" and that "nothing in a plan can name
what it draws". `_bake_uncached` returns (guid, ifc_class, mesh) and its own
docstring credits R38-PLAN-IDENTITY; `cut_baked_guided` emits (guid, class,
polyline) with a PRODUCTION caller in the plan renderer; the SVG carries
data-guid and planPane.ts selects on it. The entry described two functions
accurately and drew the wrong conclusion because it never looked for a third.
What actually remains: it claims three open children and names none.

CLAUDE.md's viewer numbers were both stale — "twenty-eight commits" and "3,444
lines" are now 67 and 2,570. Unlike the Node and Python drifts that file already
records, this one moved in the direction that STRENGTHENS its argument, which is
the hardest kind to notice: a number that decays toward the conclusion it
supports never looks wrong.

R39-DECOMP-VIEWER (17) — field verification out of app.ts (2,571 -> 2,508).

app.ts is not a class, so REL-4's "grep the this. refs first" rule has no this.
to grep: the file is ONE 2,445-line function and everything in it is a closure.
The equivalent is how many SIBLING closures a candidate captures, and over all
fourteen candidates >=25 lines exactly ONE captured zero. buildToolsPanel
captures 14, handleKey 12, selectByGuids 6 — every other move would have been the
callback bag REL-4 warns about. Four of five free variables already travelled on
the typed ViewerCtx, so the deps object is that context narrowed.

THE NARRATIVE-CHAIN GATE REFUSED THE FIRST RATCHET ENTRY, CORRECTLY. The previous
entry ended at 2,571 and the file measured 2,570 — one line had left with no
slice recording it, the drift the roadmap cell already documents from another
lane. The entry now runs 2,571 -> 2,508 and names the stray rather than starting
at a number nobody can reproduce. Ratchet mutation-checked at 2,507.

2072 web tests, tsc + eslint + build clean, 8 structural gates green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* SCALE-SEAM (102) — counterparty risk, client.ts 603 -> 589

`prequalScores`, `coiExpiry` and `lienExposure` out to
`apps/web/src/api/counterpartyRisk.ts` — which trade partner is a risk on this
job, and why: are they qualified, are they insured, and do we owe them enough to
be liened.

THE WITNESS IS THAT THE SEAM DISAGREES WITH THE ROUTE PREFIX. Two sit under
/prequal/ and one under /payapp/lien-exposure, so a prefix grouping would have
SPLIT the set — while all three return per-counterparty rows carrying a verdict
about that counterparty: risk_band + flags, days-to-expiry, exposure +
vendors_at_risk.

That is the affirmative form of a rule this repo has only recorded negatively:
(85) rejected "they are all multipart uploads", (89) "they are all module
records", annotate.ts "they all call editIfc" after measuring 24 recipes across
nine categories. A shared mechanism is not a question. Here the mechanism argues
AGAINST the grouping and the shape of the returns argues for it, so the evidence
is not something a name could have produced.

benchmarkResponseRates sits immediately above them and STAYED: it returns
RFI/submittal turnaround and names no counterparty at all — it measures how
responsive the process is. Adjacency is not a relationship, which REL-4 recorded
three separate times this cycle.

Found on the way out: an orphaned PrequalScores type import, the same residue
slice (101) left with EnergyResult.

Ratchet 603 -> 589, mutation-checked at 588 (both the growth assertion and the
history-chain assertion fire). 2072 web tests, tsc + eslint clean, doc gates green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Review fixes on #442, and a gate for the number that keeps drifting

Four CodeRabbit findings, all verified against the tree first. The second was
self-referential and is the interesting one.

This PR corrected CLAUDE.md's stale app.ts line count from "3,444" to 2,570 --
and then R39-DECOMP-VIEWER (17), in the same PR, took the file to 2,508. The
paragraph diagnosing numbers that decay toward the conclusion they support
decayed toward its own conclusion before it merged, and a review bot found it
rather than the author.

So test_claude_md_gates.py now checks that number against the ratchet. The
existing gate asks whether a cited FILE exists; this asks whether a cited NUMBER
is still true. It is cheap only because the value is not really CLAUDE.md's to
hold: test_file_sizes.py already pins the same file at an exact size, so the
prose is a COPY of a gated value, and a copy is what drifts. Mutation-checked
both ways -- a wrong figure fails, and a REWORDED SENTENCE fails too rather than
passing on two Nones, which is the vacuous-green failure that file's own header
calls worse than no gate at all.

R38-SYNC-2D3D is CLOSED, with its children named. The entry claimed three of
four children were open and named none of them. Re-derived by grepping the tree
rather than reading the file that was already wrong: R38-SYNC-SELECT,
R38-SYNC-VIEW, R38-PLAN-TRANSFORM and R38-PLAN-IDENTITY, and
docs/roadmap-completed.md carries a check for EACH. The 2026-08-10 un-archive
was mechanically right -- a lane row pointed at nothing -- and then inherited
the restored text's open count as though the restore had verified it. Nothing
had: R38-PLAN-IDENTITY was marked done that same day, in the archive the entry
was being pulled out of. Un-archiving restores an entry's TEXT, not its truth.

NAMING THOSE CHILDREN MADE THEM ITEMS, AND THE GATES SAID SO. Four bold item
codes in roadmap.md put three new orphans in roadmapLanes.test.ts and a stale
open-vs-implemented pair in roadmapStale.test.ts. The fourth escaped only
because its line happened to contain a check mark in prose. All four now carry
an explicit marker -- passing by accident and passing by construction look
identical until something moves.

Also: completed the verbless counterparty-risk changelog entry, and gave the
bare `wc -l` in CLAUDE.md's re-measure command its argument, since an
instruction to verify that hangs on stdin is one nobody runs twice.

Verified: 2072 web tests, tsc + eslint clean, roadmap lane/stale gates green,
citation gate green and mutation-checked twice.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* SCALE-SEAM (103) — acceptance gates, client.ts 589 -> 572

permitReadiness, diligenceReadiness, handoverAcceptance and validate ->
acceptanceGates.ts: "will an outside party accept this project, and what is
blocking it".

NEITHER THE ROUTE NOR THE AUDIENCE PRODUCES THIS GROUPING. The four routes are
/permit/readiness, /diligence/readiness, /handover/acceptance and /validate --
four different prefixes, so a prefix grouping takes one each and the set never
forms; the shared leaf word "readiness" reaches only two of the four. The
deciding parties are an AHJ, an investor, an owner and an IDS checker -- four
different audiences, so grouping by reader fails too.

What forms it is the RETURN SHAPE: each collapses the whole project to a single
accept/refuse verdict (verdict / go / accepted / status:"pass"|"fail") and then
enumerates what withholds it. (102) was carried by a prefix that actively
DISAGREED with the seam; this one by a vocabulary that says nothing at all --
four names sharing no words can still be one question, which is the inverse of
the error (85), (89) and annotate.ts each recorded, where a shared mechanism
looked like a shared question.

THE TWO EXCLUSIONS DID THE WORK. spineTraceability is the closest miss -- same
domain, adjacent in the file, equally project-scoped -- and returns
coverage/gaps/chain with NO verdict field at all: it maps completeness for a
human rather than deciding acceptance. editPrecheck DOES return a verdict, but
judges a PENDING ACTION ("may I run this recipe with these params"), is remedied
by changing the params you are about to submit, and sits beside addCurtainWall
as the precheck for editIfc.

ONE FALSE POSITIVE, RECORDED BECAUSE IT WAS INVISIBLE. A scan for verdict-shaped
returns also flagged collabSnapshot -- but the match came from the doc comment
introducing permitReadiness, the NEXT method. A method-body splitter that runs
to the next header swallows the comment belonging to that header, so the
population silently inherits its neighbour's vocabulary; a count of six looked
entirely checked. Only reading each candidate caught it.

Also files handoverAcceptance, which an earlier slice had parked under an
explicit UNFILED note asking for it to be placed by what it ANSWERS rather than
by what it sits next to. That note is narrowed to two entries, not deleted --
the other two are still genuinely unfiled, and a note that silently loses
entries is how earlier slices lost methods.

THE DOC-STRAND GATE CAUGHT A DEFECT IN THIS SLICE'S OWN NEW FILE: a /** */ doc
comment on the Ctor type sat directly below the module header, which that gate
reads as a stranded comment -- the header carrying the whole witness was one
line from reading as documentation of a type alias. It is a // comment now,
which is why counterpartyRisk.ts has none there either. The fast checks (tsc,
eslint) were clean while this was broken; the suite is where it lived.

Verified: 2072 web tests / 205 files, tsc + eslint clean, whole-tree ruff clean,
ratchet mutation-checked at 571 (both the growth and chain-end assertions fire),
48-entry narrative chain unbroken, test_route_reachability + test_reachable +
test_import_cycles + test_doc_substance + test_claude_md_gates + test_ruff_scope
+ test_declared_imports green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* SCALE-SEAM (104) — coverage maps, client.ts 572 -> 554

spineTraceability + scopeRegister -> coverageMaps.ts: "how completely is this
project's chain of records linked, and exactly what is missing".

THIS IS THE AFFIRMATIVE HALF OF A BOUNDARY (103) DREW BY EXCLUSION.
acceptanceGates.ts took the four methods that collapse the project to one
accept/refuse verdict, and named spineTraceability as the closest miss PRECISELY
because it maps completeness rather than deciding. Both members here report
proportion-complete across several link types (specs_packaged_pct /
packages_costed_pct / sheets_specced_pct / spec_to_budget_pct; pct_quantified /
pct_allocated / pct_scheduled) plus the individual records lacking the link
(specs_without_bid_package / bid_packages_without_cost_code / sheets_without_spec;
gap_items with per-item gaps[] and status complete|gap). Neither carries a
verdict field. Same test as (103), run for inclusion this time.

DERIVING THE POPULATION REQUIRED RESOLVING NAMED RETURN TYPES, AND THAT IS THE
LESSON. A scan of method bodies for coverage vocabulary returned scopeRegister,
citedQuery and progressActuals -- and MISSED spineTraceability, the strongest
member, because its return is the named type SpineTraceability and its body
contains none of those words. That is the exact MIRROR of the mistake (103)
recorded, where a body scan OVER-counted by matching the doc comment of the next
method. A textual scan of a typed language reads neither the comments nor the
types correctly: it finds candidates, it never counts them.

EXCLUSIONS. citedQuery carries coverage / uncited_claims / fully_cited, but its
product is an ANSWER whose sourcing those annotate -- the caller renders a cited
answer, not a worklist. masterBuilderBrief is THE CLOSEST CALL in this slice,
closer than spineTraceability was to the gates, since it has readiness_pct,
ready_steps and gap_steps; it stays because its product is a narrative brief with
a reframe_prompt and a disclaimer, where the percentages head a document rather
than being it -- recorded rather than asserted, since a later reader may decide
otherwise. progressActuals pct_complete is physical progress against a planned
quantity banded ahead/on_track/behind: variance over time, not completeness of
linkage.

A FOLLOW-UP PROPOSED IN (103) IS WITHDRAWN, AND THAT IS A CORRECTION. #443 said
three consecutive slices leaving an orphaned type import was "a pattern that
wants a gate rather than vigilance". It already has one: tsc reports the orphan
as TS6196 and caught every instance -- EnergyResult (101), PrequalScores (102),
DiligenceReadiness (103) and now SpineTraceability (104). None reached a commit.
Proposing a gate for a class the toolchain already gates is how a checklist grows
without getting safer.

Verified: 2072 web tests / 205 files, tsc + eslint clean, whole-tree ruff clean,
ratchet mutation-checked at 553 (3 assertions fire), 49-entry narrative chain
unbroken, and test_claude_md_gates + test_route_reachability + test_reachable +
test_import_cycles + test_doc_substance + test_ruff_scope + test_declared_imports
all green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* The app.ts figure was wrong in four places; the gate reached one

ROADMAP-TRUTH. The R39-DECOMP-VIEWER entry carried THREE different figures for
one file: a header saying app.ts is "5,160 -> 3,311, a 36% cut", a shipped block
saying "5,160 -> 2,944, a 43% cut", and the ratchet pinning 2,508. A fourth sat
elsewhere in the file ("5,064 -> 3,444 -> and thirteen slices since"). The header
also claimed "seven slices shipped" directly above a list naming eleven.

BOTH BASELINES WERE REAL AND NEITHER WAS LABELLED. CLAUDE.md measures from 5,064,
the file before the first extraction commit of 2026-08-06; the roadmap measured
from 5,160, a SAME-DAY PEAK partway through it -- the file grew before it shrank.
Nothing on the page could tell a reader they were counted from different points.
Baseline is now stated, matches CLAUDE.md, and the current figure is the
ratchet's own count. Slice count is deliberately not restated: the ratchet
comment is the record, and a count repeated in prose is another copy that drifts.

THE GATE IS THE REAL SUBJECT. The previous release added a check binding
CLAUDE.md's narrative app.ts figure to the test_file_sizes.py pin, reasoning that
prose is a copy of a gated value and a copy is what drifts. The reasoning was
right; the implementation was too narrow. It gated ONE copy of a number living in
FOUR places, and the other three were already wrong when it shipped. Gating the
instance you happened to be looking at is not gating the class. The check now
scans every doc carrying the baseline-anchored form -- and immediately earned it,
failing on a third stale figure I had missed by reading.

MUTATION TESTING THEN FOUND A DEFECT IN THE WIDENED CHECK ITSELF. Its first draft
used a SUMMED floor ("at least 2 figures across the docs") and reported "3 figures
across 2 docs" while all three came from the roadmap: CLAUDE.md words it "5,064
lines to", so the arrow pattern never matched it and its contribution was ZERO. A
mutation reformatting only the roadmap took the count to 0 and exposed it. That is
exactly the per-doc vacuity failure this same file's citation ratchet exists to
prevent, repeated one screen further down. The floor is now PER-DOC and CLAUDE.md
is covered by name rather than by assumption.

Mutation-checked three ways: a wrong figure fails, a vanished figure fails the
per-doc floor, and the restored state passes.

Verified: whole-tree ruff clean, 389 shell tests / 27 files, and test_file_sizes +
test_claude_md_gates + test_route_reachability + test_reachable +
test_import_cycles + test_doc_substance + test_ruff_scope + test_declared_imports
all green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

* Fix an unmatched ** I introduced while writing about drift

markdownlint MD037 at docs/roadmap.md:2552, flagged in review and verified: my
correction to the R39-DECOMP-VIEWER header opened ** at "app.ts is 5,064..." and
closed it at "entirely gone.**", then left a STRAY CLOSING ** after "named
eleven." with no opener.

Same defect class CodeRabbit flagged on #442 (the unmatched ** on the R38
heading, which predated me) -- introduced fresh, in the same file, in a paragraph
whose subject is copies that drift. Balanced now: 4 delimiters across the block.

Gates re-run: test_claude_md_gates, test_file_sizes, and 389 shell tests / 27
files all green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt2XKB83wwNt2nrMbK6eEA

---------

Co-authored-by: Claude <noreply@anthropic.com>